nexus-mcp

by Talya1412

Overview Schema Related Servers Score Discussions

Python

Local

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.1.0
Disambiguation3/5
Many tools are clearly distinct, but there are several overlapping groups such as nexus_get_mod vs nexus_get_mod_v2, nexus_get_files_v2 vs nexus_get_mod_files vs nexus_get_files_by_uid, and multiple tag/comment tools that cover similar actions. The descriptions help differentiate them, but an agent can easily misselect between v1/v2 variants or between discard, hide, lock, and remove operations.
Naming Consistency4/5
The tool names almost universally follow a nexus_verb_noun snake_case pattern, which is predictable and readable. Minor deviations include v2 suffixes, raw GraphQL tools (nexus_graphql_query, nexus_graphql_introspect), and inconsistent synonym choices like discard/remove/untrack/unblock, but these are not enough to make the naming chaotic.
Tool Count1/5
135 tools is an extreme count for a single MCP server, far exceeding even the 50+ threshold for a serious mismatch. While Nexus Mods is a broad platform, this surface area creates an overwhelming selection problem and dilutes the coherence of the tool set.
Completeness5/5
The tool set provides extremely thorough coverage of the Nexus Mods domain: mods, files, games, collections, revisions, comments, users, tags, endorsements, OAuth, donation points, moderation, and user preferences. The raw GraphQL query escape hatch also fills any residual read-side gaps, so there are no obvious dead ends.
Average 4.2/5 across 129 of 135 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 12 of 12 community issues answered or closed in the last 6 months
- 32 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation safety profile is covered. The description adds the ownership requirement, the 'published' state prerequisite, and the return shape ('JSON {success} or an error string'), which are useful. It does not disclose deeper consequences such as whether retraction is reversible or what exactly happens to the revision.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a return-value note. There is no filler or repetition of schema content. It could arguably be a single sentence, but the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering destructive/readOnly/idempotent behavior and an output schema available, the description provides the essential preconditions ('published', 'must own it'). However, it omits any mention of how retraction interacts with other revision operations or what happens to the collection after retraction. For a destructive tool, a bit more lifecycle context would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers both parameters with 100% description coverage: 'Retraction reason.' and 'Revision ID.' The tool description adds no additional semantic detail about these parameters, but with complete schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Retract a published collection revision' with a specific verb and resource. It adds meaningful qualifiers ('must own it', 'published') that help an agent understand the operation. However, it does not explicitly distinguish this from the sibling nexus_discard_revision, so it falls short of full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite ('must own it') but provides no guidance on when to use this tool versus alternatives like nexus_discard_revision or nexus_publish_revision. There is no when-not-to-use guidance or explanation of how this relates to the collection revision lifecycle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds the return format ('JSON {message: ...}') and the authentication scope, but does not add meaningful behavioral context beyond what annotations convey, such as side effects or reversibility. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no fluff: the first states the action, the second states the return type. It is appropriately concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple untrack operation, the description covers the action and return format, and the schema covers parameters and annotations cover safety traits. However, it lacks explicit usage context (e.g., must be tracked first, inverse of nexus_track_mod) and could mention potential errors or idempotency notes. It is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both parameters (mod_id and domain_name including an example and a NOT warning). The tool description adds no additional parameter semantics, so it stays at the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Stop tracking' and the resource 'mod', scoped to 'the authenticated account'. It is not a tautology and distinguishes the action from its sibling nexus_track_mod by implying the inverse operation, though it does not explicitly name the sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., the mod must be currently tracked), and no context about authentication requirements beyond the implied 'authenticated account'. It offers no 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds a return shape ('JSON {comment: {id}} or an error string') and identifies the API as v2 GraphQL, but it does not disclose permission requirements, side effects beyond clearing the status, or how errors are raised.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: the action is stated first, followed by a concise return summary. There is no filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with useful annotations and a described return value, the definition is mostly complete. It would be stronger with one sentence differentiating comment-level clearing from thread-level clearing, but that is a minor gap at this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter comment_id is already documented with type, minimum, and a 'Comment ID' explanation. The description adds no additional meaning about how to specify or interpret the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('clear'), a specific resource ('a comment's moderation status'), and a clarifying parenthetical ('moderator permissions'). It is clear and not tautological, though it does not explicitly distinguish itself from the closely related sibling nexus_clear_comment_thread_moderation_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool over alternatives, no prerequisites, and no when-not-to-use conditions. The intended use is only implied by the action name and short description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, non-destructive, and open-world, so the description only needs to add context beyond those. It adds that this is a v2 GraphQL endpoint and that the result is a JSON list with specific fields, which is useful but modest; no rate-limit, pagination, or exact-match caveats are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and the return list is presented compactly. Every sentence contributes either to what the tool does or what it returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only lookup with full schema coverage and an output schema, the essential operational context is present. However, the description does not address the ambiguity with nexus_search_by_md5, so the contextual picture is not fully complete for an agent choosing among similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the md5 parameter is described as 'MD5 hash of the file,' which is unambiguous. The tool description restates the lookup concept but adds no additional parameter semantics beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Look up which mod file matches an MD5 hash') and clearly identifies the resource and purpose. It is clear, but it does not explicitly distinguish itself from the similarly named sibling nexus_search_by_md5, so it falls short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as nexus_search_by_md5, nexus_get_file_hashes, or nexus_get_file_info. The description relies entirely on the tool name and the one-line purpose, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful detail about the fixed limit of 10 results and the array return type, but otherwise does not describe additional behavioral traits such as sorting or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence conveys the operation, scope, count limit, and output type without filler. Every part of the description contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool with a rich output schema and strong annotations, the description is nearly complete. The only notable gap is the lack of clarification against similarly named sibling tools, which could cause an agent to select the wrong endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully covers the only parameter, domain_name, including examples and the note that it is not the display name. The description adds no extra parameter semantics beyond indicating the tool operates 'for a game,' so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific operation: get the 10 most recently updated mods for a game, and it notes the return shape as an array of mod info objects. It is clear but does not explicitly differentiate itself from similar siblings like nexus_get_updated_mods or nexus_get_latest_added.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus similar alternatives such as nexus_get_updated_mods, nexus_get_latest_added, or nexus_get_trending. The phrase 'for a game' implies the scope but does not help an agent choose among the closely related listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that this is the GraphQL v2 endpoint and lists the returned fields, which is useful but does not disclose filter semantics, pagination, or authorization behavior. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loaded with the core purpose, and includes a compact return structure. Every sentence contributes useful information with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations, a complete input schema, and an output schema cover most operational details. The main gap is the lack of guidance distinguishing this v2 endpoint from the legacy nexus_get_tags tool, which is relevant context for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters are documented in the input schema. The description only refers to them generically as 'optional filters' and adds no additional semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List tags' and the resource, with optional filters and the GraphQL v2 context. However, it does not differentiate from the sibling tool nexus_get_tags, so an agent may not know which variant to select.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as nexus_get_tags, nexus_get_tag_by_id, or nexus_get_tag_categories. There are no exclusions, prerequisites, or selection criteria mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return shape (JSON list of {id, name, domainName, modCount, collectionCount}) and mentions 'v2 GraphQL', which is useful context. However, it does not disclose pagination, ordering, or potential errors. Given the strong annotation coverage, a score of 3 is appropriate: it adds some behavioral detail but not extensive context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences that front-load the purpose and then specify the return format. Every word earns its place, with no filler or repetition. It is clear, well-structured, and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with an output schema, the description covers the core information an agent needs: what it does and what it returns. It mentions the fields in the JSON list. Minor gaps include absence of pagination or limit details, but given the tool's simplicity and the presence of annotations covering safety, it is sufficiently complete. The mention of 'v2 GraphQL' also adds context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is trivially 100%. There is nothing to explain about parameters. The description does not need to compensate for undocumented parameters because there are none. According to the rubric, with 0 parameters the baseline is 4, and the description does not need to add anything further in this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'lists games that support collections', specifying the verb, resource, and a specific constraint (support for collections). It also mentions 'v2 GraphQL' which hints at the technology. While it distinguishes from generic game listing tools like nexus_get_games by the collection filter, it does not explicitly name any sibling for contrast, so it misses the top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where nexus_get_games or other game-related tools would be more appropriate, nor any exclusions or preconditions. The usage context is only implied (if you need games that support collections), but there is no explicit routing or differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare read-only, idempotent, non-destructive behavior, and the description adds the return shape. It does not disclose potential external calls, failure behavior, or provider-specific limitations, but the annotation coverage lowers the burden here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core action in the first sentence and the return shape in a short second line. The parenthetical 'v2 GraphQL' is mildly redundant with the title but does not undermine clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, one-parameter, read-only tool with an output schema and safety annotations, the description provides sufficient context. The main omission is explicit guidance on when to use this tool versus related lookup tools, but this is not critical given the tool's narrow scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully described in the schema as 'External video URL (YouTube etc.)'. The description's reference to 'external video URL' provides negligible additional meaning beyond what the schema already includes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool resolves an external video URL into embed metadata, and it lists the concrete fields returned. This makes the tool's purpose specific enough to distinguish it from most siblings, though it does not explicitly name a differentiating sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: you have an external video URL and need embed metadata. However, the description does not explicitly state when to prefer this tool over alternatives, nor does it provide usage context such as supported URL patterns beyond the schema's 'YouTube etc.' note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds return-shape context (totalCount, filteredCount, uploads with status/hash fields) and notes the GraphQL v2 implementation, but does not disclose auth needs, rate limits, or pagination behavior beyond what the schema already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one purpose sentence followed by a concise return-shape summary. There is no wasted language, and the '...' appropriately signals additional fields without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 12-parameter listing tool with output schema and strong safety annotations, the description is adequate but leaves gaps. It does not explain filter/search semantics, sort behavior, or when this upload listing is preferable over the many sibling file/upload tools, so an agent may struggle to invoke it with the right intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description does not add meaning to ambiguous fields like 'filter' or 'search', but those are already minimally described in the schema. No parameter insight is provided beyond the structured schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List') and resource ('mod file uploads') and adds a distinguishing detail ('with scan status', 'v2 GraphQL'), which sets it apart from other list/file tools. Even though the annotation title says 'your uploads', the description clearly identifies the resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool vs alternatives like nexus_get_files_v2 or nexus_get_mod_files, and no excluded cases. It merely states what the tool does, leaving the agent to infer selection from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond annotations by warning that privacy-restricted accounts may hide the report due to an API-side restriction, not a tool failure. It also clarifies the v2 GraphQL nature of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and well-organized with a distinct note and return shape. The detailed return JSON is somewhat redundant given an output schema exists, but the overall length is reasonable and every section is clearly separated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation, a key edge-case behavior, and the return shape. With strong annotations, complete schema coverage, and an output schema present, the main missing piece is explicit guidance on how this tool relates to summary/report listing tools or when to choose it over them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents both account_id and report_id. The description does not add extra parameter semantics beyond what the schema provides, but it also does not need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get one monthly Donation Points report by report ID'. It clearly identifies the operation and scope, though it does not explicitly differentiate itself from sibling tools like nexus_get_user_monthly_summary or nexus_get_user_monthly_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool versus alternatives or mention exclusions. The note about privacy-restricted accounts is behavior-related, not usage guidance. The schema parameter description hints at using summary entries, but the tool description itself provides no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveHint=true and idempotentHint=false, so the mutation profile is known. The description adds minor context by identifying the affected resource as an endorsement and indicating the expected response status, but it does not explain consequences, reversibility, or authorization requirements beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the operation, and includes only the essential return-status information. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity, three-required-parameter tool with full schema descriptions, annotations, and an output schema, the description provides sufficient operational context. It would benefit from explicitly noting whether abstaining requires an existing endorsement or is irreversible, but nothing critical for invoking the tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented in the schema itself. The description does not add extra semantics such as how abstaining relates to a specific version or what domain_name means, so it provides no additional value beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('withdraw or abstain from an endorsement') and names the target resource (a mod), which clearly communicates the core operation. It does not explicitly name a sibling alternative such as nexus_endorse_mod, but the semantic contrast is strong enough for an agent to distinguish the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when the tool should be used ('withdraw or abstain from an endorsement') but provides no explicit guidance about when to prefer it over nexus_endorse_mod or nexus_get_endorsements, nor any exclusions or prerequisites. This is usable but leaves the selection logic implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds the return format (JSON {commentThread: {id}} or error string) and the GraphQL version, but does not elaborate on side effects, permission requirements, or what 'moderation status' clearing visibly changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action. The return format is clearly separated, and there is no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with complete schema coverage, an output schema indicator, and annotations covering idempotency and destructiveness, the description is nearly sufficient. The only notable gap is the absence of usage context, but that is already penalized in usage_guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% parameter description coverage with 'comment_thread_id' documented as 'Comment thread ID.' The description adds no further meaning to the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Clear'), a specific resource ('comment thread's moderation status'), and disambiguates with '(moderator permissions)'. It also notes the API flavor ('via v2 GraphQL'), and the verb+resource combination distinguishes it from siblings like nexus_clear_comment_moderation_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. It does not mention the sibling nexus_clear_comment_moderation_status or explain the difference between clearing a thread's status and a comment's status, leaving the agent to infer applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation with no destructive or idempotent behavior, and the description adds a small but useful return-shape detail: JSON {success} or an error string. However, it does not disclose auth requirements, rate limits, or side effects beyond the annotated basics. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly written: one action sentence and a clearly separated return note. No filler or redundant wording, and the main purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter tool with full schema coverage, an output schema, and annotations covering the safety profile, the description is largely sufficient. It could mention authentication or rate-limit expectations, but no critical information for invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'to', 'title', and 'body'. The description's 'one or more users' aligns with the comma-separated recipient IDs in the schema but does not add meaningful semantic value beyond it. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Send') and resource ('private message to one or more users'), making the tool's purpose immediately clear. It also distinguishes itself from sibling read-oriented tools like nexus_get_private_message_url. The GraphQL v2 mention adds useful transport context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives, nor any exclusions or prerequisites. It only restates the operation without explaining how it fits among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes beyond annotations by disclosing the return contents, including the 'categories' list and its fields. There is no contradiction between the description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the action and scope, and the second block explains the return format. There is no filler or repetition of schema details, so every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one required parameter and an existing output schema, the description is nearly complete. It explains the purpose, key return fields, and category structure. The only notable gap is the lack of any guidance distinguishing this tool from the similarly named nexus_get_game_v2, which could matter for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter, domain_name, is already well documented with format guidance, examples, and a warning against display names. The tool description adds no additional parameter-level meaning, which is acceptable because the schema fully carries that burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Get details for one game' and enumerates what is included (stats, file counts, download counts, categories). It differentiates itself from plural siblings like nexus_get_games by emphasizing 'one game,' but it does not distinguish itself from nexus_get_game_v2, which appears to serve the same singular purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. The phrase 'for one game' implies it is for a single game rather than a list, but the description never names sibling tools like nexus_get_games or nexus_get_game_v2, nor explains trade-offs. This leaves the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the return shape and notes it is v2 GraphQL, which is useful, but it does not disclose error behavior, auth needs, or any edge-case behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the core purpose. It presents the return JSON in a clear block, and every sentence adds useful information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 and complete parameter documentation, the description is sufficient. It could strengthen sibling differentiation, but nothing essential for invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the category_id parameter is documented as 'Tag category ID.' The description adds no further semantic detail beyond restating the ID parameter, so it does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a single tag category by ID') and identifies the resource (tag category). It is distinguishable from the sibling tools like nexus_get_tag_by_id and nexus_get_tag_categories by specifying the singular 'tag category' target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied: call this when you need one tag category by ID. However, there is no explicit guidance on when to prefer it over related tools such as nexus_get_tag_categories or nexus_get_categories, nor any mention of when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal mutation/destruction (readOnlyHint=false, destructiveHint=true), and the description adds useful context: required permissions, v2 GraphQL, and the return shape ({comment: {id}} or error). It does not contradict the annotations, though it does not elaborate on the visibility side effects of hiding beyond the word itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences front-load the operation and permission, then give the return shape with no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-param mutation with complete schema coverage and an output summary, the description covers the essentials: operation, permission, API, and return format. It lacks any note about reversibility or relation to restore/discard, which would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (reason, comment_id, internal_reason) already has a meaningful description in the schema. The tool description adds no parameter-specific detail, so it meets but does not exceed the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Hide') and resource ('a comment'), plus moderator permission and API version, which makes the operation recognizable. It does not explicitly differentiate from sibling comment-moderation tools like nexus_discard_comment or nexus_lock_comment, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Only the prerequisite 'moderator permissions required' is given; there is no guidance on when to choose hide over discard, restore, lock, or clear moderation status. The agent must infer usage from the name and schema, with no exclusions or alternatives named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to restate those. The description adds the context of 'active moderation' and the return shape, but does not disclose side effects, failure conditions, authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loads the purpose, and uses a compact return-format block. Every sentence adds value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with annotations and an output schema, the description is adequately complete. It covers the operation, scope, and return format, though slightly more context about when the operation is valid or what errors might occur would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting both moderation_id and description. The tool description does not add meaningful parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Submit a fix for an active moderation on your content (v2 GraphQL).' It clearly identifies the operation and scope, though it does not explicitly distinguish itself from sibling moderation-related tools such as nexus_clear_comment_moderation_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the phrase 'for an active moderation on your content,' suggesting the tool should be used when a moderation fix is needed. However, there is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description's burden is reduced. It adds the endpoint and the success/error return shape, but does not describe side effects, required authentication, or behavior when both parameters are omitted. No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the core action in the first sentence and a compact return summary. Both sentences earn their place, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-optional-parameter mutation with a clear schema, annotations, and a stated return shape, the description is mostly complete. A small gap is the absence of authentication context or clarification of country value format beyond 'name/code', but the schema covers the essential invocation semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both `country` and `user_id` are already explained with optionality and default behavior. The description adds no parameter-level detail beyond what the schema already provides, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update a user's country') and the implementation route ('via v2 GraphQL'). This clearly distinguishes it from sibling profile-update tools such as nexus_update_about_me and nexus_update_preferences by naming the exact resource being modified.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given about when to use this tool versus alternatives. There is no mention of when not to use it, no stated prerequisites, and no comparison to related update tools. The intended use must be inferred almost entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description adds value by stating the ownership authorization requirement and the success/error return shape. It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single front-loaded sentence plus a compact Returns block. No redundant prose; version and ownership details are integrated succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Schema, annotations, and output schema cover the mechanics and safety profile, and ownership is stated. However the description leaves the revision lifecycle ambiguous—particularly when to discard vs retract and whether discard is restricted to unpublished revisions—so an agent may mis-route to a sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each property has a clear description, so the baseline applies. The tool description adds no parameter-specific detail beyond the schema, aside from tying collection_id to ownership.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description provides a specific verb 'Discard' and resource 'collection revision', and includes an ownership precondition. However it doesn't differentiate from sibling tools like nexus_retract_revision or nexus_discard_collection, so it stops short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when an owning user wants to discard a revision, but gives no explicit when/when-not conditions or alternative routing to nexus_retract_revision/nexus_discard_collection. 'Must own the collection' is the only contextual precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds valuable context: the operation is a soft-delete rather than a hard delete, moderator permissions may be required, and the response is either {success} or an error string. This complements the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the action and resource in the first clause. The return-value note is useful, though the parenthetical 'via v2 GraphQL' is somewhat redundant and could be omitted without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive operation, the description covers the action, the authorization caveat, and the return shape, while the schema fully documents the parameter. It lacks usage differentiation against related tag tools, but that gap is already reflected in the usage_guidelines score, and the overall complexity is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single parameter tag_id is fully documented as an integer with minimum 1 and the description 'Tag ID.' The tool description adds no parameter-specific detail beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Discard') and resource ('a tag'), clarifies that the operation is a soft-delete, and identifies the v2 GraphQL interface. This clearly distinguishes it from related tag operations in the sibling list such as create_tag, update_tag, block_tag, and get_tag_by_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like nexus_block_tag, nexus_update_tag, or nexus_unblock_tag. The only condition mentioned, that moderator permissions may be required, is a prerequisite rather than a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the return shape (JSON with verified and externalVerificationIds), which is useful context, though it does not discuss auth, errors, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose, followed by a compact return format. The 'v2 GraphQL' note is slightly extra but not distracting, and every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter, a rich output schema, and safety annotations, the description is nearly complete. It could be improved by explicitly naming the related verification flow tools, but this is a minor gap rather than a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter user_id is fully documented in the schema with 'User ID. Omit for the current user.', providing 100% schema description coverage. The description itself adds no additional parameter-level meaning, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('a user's age verification status'), which clearly identifies the tool's function. It is easily distinguished from sibling tools like nexus_start_age_verification_flow because it reads rather than initiates a flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving age verification status, but it does not explicitly mention when to use it over alternatives or when not to use it. The differentiation from the start/appeal flow tools is left to inference from the tool names and the 'Get' wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context: it uses GraphQL v2 and defines the exact return keys (schemaV1 vs schemaV2). No contradictions or unmentioned side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences plus a compact return block, with the main action front-loaded. Every element earns its place and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with safety annotations and an output schema, the description is nearly complete. The only minor gap is that 'current game' is not explicitly defined, though the zero-parameter signature makes the intended use reasonably inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so no parameter-level documentation is needed. The schema coverage is 100% and the description contains no parameter information, which is appropriate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 the current game artwork schema URLs (v2 GraphQL).' The return block clarifies it returns schemaV1 and schemaV2 artwork fields. It does not explicitly distinguish itself from sibling getters, so it misses full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives such as nexus_get_game, nexus_get_game_v2, or nexus_get_games. Context that this is the current game's artwork is implied but no exclusions or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the operation requires moderator permissions, communicates the transport ('via v2 GraphQL'), and specifies the return shape ('JSON {success} or an error string'). These details add behavioral context beyond the annotations, which already indicate idempotency, non-read-only, and non-destructive behavior. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action. Every sentence adds value: the action, the permission requirement, the transport, and the return format. There is no redundant filler or unnecessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 required scalar params, output schema present, annotations covering idempotency and safety), the description is largely complete. It covers the permission requirement and return value. The only notable gap is the absence of explicit alternative guidance, which is minor for such a straightforward mutation and does not significantly impair an agent's ability to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% description coverage for both parameters, with badge_id pointing to nexus_get_badges and collection_id described as 'Collection ID.' The tool description itself adds no additional parameter semantics, so the baseline of 3 is appropriate rather than a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Award a badge to a collection.' This clearly identifies the action and target, and the inclusion of 'moderator permissions required' adds important context. It is distinct from the sibling nexus_remove_badge_from_collection by virtue of the opposing action, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions a prerequisite ('moderator permissions required') but does not reference sibling tools like nexus_remove_badge_from_collection or explicitly state that this is the tool to use when awarding a badge. Usage context is left entirely to inference from the tool name and action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description does not contradict them. The description adds that this uses v2 GraphQL and lists the return fields, which is useful context. It does not disclose batch size limits, invalid-hash behavior, or authentication requirements, but for a safe read operation with rich annotations this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single clear purpose sentence followed by a compact return-format list. Every element earns its place, and there is no redundant restatement of the tool name or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only, idempotent tool with an output schema, the description is nearly complete. It defines the operation and the response shape. The only notable gap is lack of distinction from the very similar sibling nexus_search_by_md5, which an agent might need to choose correctly, but the simple schema and annotations keep this from being a serious omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the md5s parameter already described as 'Comma-separated MD5 hashes.' The tool description adds the word 'batch' but no additional format details such as case sensitivity, whitespace handling, or maximum number of hashes. This is a standard baseline case where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation and resource: given MD5 hashes, find matching mod files. It clearly communicates the reverse lookup direction (hashes in, file metadata out), which distinguishes it from names like nexus_get_file_hash that could imply returning hashes. The 'batch' qualifier further distinguishes it from single-hash tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you have a batch of MD5 hashes to resolve to file details. However, it does not explicitly address alternatives like nexus_search_by_md5 or nexus_get_file_hash, and it gives no 'when not to use' guidance. The intended use case is inferable but not explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by stating the response is a JSON mod info object and that it is server-cached for 5 minutes, which helps set expectations about freshness. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with its core purpose and uses a separate Returns section for response details. It is compact and informative, though the first sentence's field list overlaps somewhat with the example fields listed in the Returns section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count, high schema coverage, presence of an output schema, and strong annotations, the description provides the additional context an agent needs: return shape, example fields, and caching behavior. Nothing essential appears missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both parameters already include clear explanations and examples (e.g., domain_name examples, mod_id example). The description does not add additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Get full details for one mod' and enumerates the included fields (name, author, version, description, endorsement/download counts, upload dates). It is clear and unambiguous, though it does not explicitly differentiate itself from the sibling nexus_get_mod_v2.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need full details for a single mod rather than a list or search result. However, it does not explicitly mention alternatives or provide exclusion criteria, leaving some routing judgment to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context by stating the requirement for an authenticated account and by specifying the exact return shape ('JSON array of {mod_id, domain_name}'). This goes beyond what annotations provide and contains no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence stating the core action followed by a one-line return format. The purpose is front-loaded, and every word earns its place. No redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool, the description fully covers what it does and what it returns. It mentions the authentication requirement and the output structure. An output schema exists to further document the return value, so nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. Per rubric, the baseline for zero parameters is 4. The description appropriately omits parameter details since none exist, so no additional semantic clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('mods the authenticated account is tracking'). It distinguishes the tracking scope from generic mod list endpoints like nexus_get_trending or nexus_get_latest_added, but does not explicitly contrast with closely related siblings such as nexus_get_opted_in_mods, which could be confused for a similar list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites (other than inherent authentication), or when a different listing tool would be more appropriate. The agent must infer usage purely from the name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating (readOnlyHint=false), non-destructive, idempotent operation. The description adds useful behavioral context: it publishes the collection, requires ownership, and returns JSON {success} or an error string. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the action appears in the first line, followed by key eligibility context and a brief return note. Every sentence contributes value, and there is no filler or redundant re-explanation of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter mutation with an output schema and helpful annotations, the description covers the essential operational facts: what it does, who can use it, precondition, and return shape. It does not enumerate edge cases, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the single parameter collection_id already has a clear 'Collection ID.' description. The tool description does not add new parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — 'List (publish) a currently unlisted collection' — with a clear resource and a parenthetical clarifying that 'list' means publish, not fetch. It is distinguishable from the sibling nexus_unlist_collection, though it does not explicitly name that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: the collection must be currently unlisted and the caller must own it. It does not explicitly mention alternatives such as nexus_unlist_collection or nexus_publish_revision, and it does not state when not to use this tool, so usage 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context by specifying the JSON response shape ({url, uuid}) and the required follow-up: upload the file to the returned URL and then reference the uuid. This meaningfully explains the tool's role in a multi-step process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence states the purpose, and two short sentences describe the return value and next step. Every sentence earns its place, with no redundant or vague filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, optional-input tool with output schema and safety annotations, the description covers the core workflow well: request URL, upload file, use uuid. The only notable gap is the absence of any guidance about when to choose this tool over related upload/media tools, though that is more of a usage-guideline concern.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters having minimal but adequate descriptions ('File name including extension.' and 'MIME type.'). The tool description does not add further parameter-specific semantics, which is acceptable given the schema already documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Request a presigned URL for uploading media.' It clearly explains this is a URL-request step, not the actual upload, and mentions the v2 GraphQL context. The return shape and follow-up action ('Upload the file to url, then reference the uuid') further distinguish it from any direct-upload sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance about when to use this tool versus alternatives like nexus_upload_attachment or other media-related tools. The intended workflow is implied by the purpose, but no exclusions, prerequisites, or sibling comparisons are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=false, and the description reinforces this by calling it an ACTION. It adds useful context that initiating an appeal session has state-changing effects and that the returned URL must be opened to continue.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences front-load the action, then state the side effect and return handling. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter action with an output schema, the description covers what the tool does, what it returns, and what to do next. It is complete enough for an agent to invoke and process the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the input schema fully covers inputs. The description's mention of 'the current user' clarifies the implicit identity context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Start the age verification appeal flow for the current user') and identifies it as v2 GraphQL. It is clear enough to separate from read tools, but it does not explicitly contrast with the sibling nexus_start_age_verification_flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when the appeal flow should be started instead of the basic verification flow, or what conditions trigger an appeal. The only hint is 'This is an ACTION, not a read,' which is a behavioral warning rather than selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a non-read-only, non-idempotent, non-destructive operation. The description adds a useful return contract ('JSON {success, errors} or an error string') but does not elaborate on side effects, auth requirements, or error scenarios. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states what the tool does, gives an example, and includes the return shape. Every sentence earns its place with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that all parameters are documented in the schema and an output schema exists, the description is sufficient for correct invocation. The only minor ambiguity is whether metadata_json should be a JSON-encoded string, but the schema's type and title already clarify the structure adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all five parameters. The description's example loosely connects to the event_type parameter but adds little beyond the schema's own field descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Report an app metric' via v2 GraphQL, and provides a concrete example ('a Vortex collection install event'). It clearly communicates the tool's function, though it does not explicitly distinguish itself from sibling tools like nexus_track_mod or nexus_graphql_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use: reporting app metrics such as collection install events. It gives an actionable example but does not mention alternatives or when not to use the tool, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds a useful runtime trait: it uses the v2 GraphQL API and does NOT consume the v1 REST rate-limit quota, plus it summarizes the returned fields. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in one sentence, and the rate-limit note is valuable. The Returns block is somewhat redundant with the output schema, but it is compact and does not bloat the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, annotations, and fully described schema together cover the necessary call details: required slug, optional revision/domain/adult flags, read-only safe behavior, and the rate-limit distinction. A brief explicit pointer to sibling tools would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond what the schema already provides for slug, revision, domain_name, and view_adult_content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Get') and resource ('specific collection revision') and scopes it to mod count, sizes, and status. It clearly distinguishes itself from sibling nexus_get_collection by naming 'revision' as the target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The v2 GraphQL / rate-limit note implies a reason to prefer this tool, but there is no explicit when-to-use or when-not-to-use guidance and no named alternatives. The choice between this and nexus_get_collection or the revision-upload sibling is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description only needs to add context. It does add some useful details about returned fields (MD5, virus scan link, changelog), but it does not disclose any additional behavioral traits such as auth requirements or response considerations beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tightly written sentence that front-loads the action and resource, then lists the specific values returned. Every phrase earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With complete parameter documentation, full annotations, and an output schema present, the description is sufficient for an agent to invoke this read-only tool. It does not need to explain return values because the output schema already handles that, and no prerequisite warnings are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all three parameters already have meaningful descriptions referencing the numeric mod ID, numeric file ID, and lowercase game-domain slug. The description adds no extra parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Get details for a single file of a mod') and enumerates the exact data returned (version, size, MD5, virus scan link, changelog), which clearly separates it from sibling tools such as nexus_get_mod_files (file listing) or nexus_get_download_link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It conveys that this is for retrieving metadata about one specific mod file, which implies the use case, but it does not explicitly state when to prefer it over related tools like nexus_get_mod_files, nexus_get_file_hash, or nexus_get_mod_changelogs. No exclusions or alternates are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context about the fixed count of 10 and the trending scope, while also noting the array return shape, but it does not discuss auth, rate limits, or other operational behavior beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action and scope, with no filler or repetition. Every word contributes to the agent's understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only tool, the combination of the description, full schema documentation, annotations, and output schema is sufficient. The agent can correctly invoke it with a game domain and understand the result shape without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains domain_name with examples and the explicit 'NOT the display name' warning. The tool description only adds 'for a game', which adds no meaningful parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get the 10 currently trending mods for a game'. It also clarifies the return shape as an array of mod info objects, and the trending scope distinguishes it from sibling tools like nexus_get_latest_added or nexus_get_latest_updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving currently trending mods for a given game, but it does not explicitly say when to prefer it over similar read tools such as nexus_get_latest_added, nexus_get_latest_updated, or nexus_search_mods. No exclusions or alternative routing guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, and the description adds useful behavioral context: it states the action goes through v2 GraphQL, requires moderator permissions, and describes the return format. It says what locking does ('against further interaction') but doesn't disclose whether unlocking is possible or mention side effects like comment visibility changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two lines of core action then a clear 'Returns' section. It's front-loaded with the action and scope, and every sentence is purposeful. It could omit the redundant 'via v2 GraphQL' and focus on behavior, but overall it's well-structured and brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation with an output schema and idempotentHint, the description is complete: it covers the action, required permissions, the parameter, and the response. It doesn't need to explain return values (covered by output schema) or discuss error details since it explicitly says it returns an error string. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the parameter already well-documented ('Comment ID to lock'). The description reinforces the purpose but doesn't add much beyond the schema. However, it does specify that comment_id is the only argument, and the return format, which helps the agent understand the call. A modest improvement over baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lock a comment') and the resource ('a comment'), distinguishes itself from sibling comment tools (like nexus_hide_comment, nexus_lock_comment_thread) by specifying it locks the comment itself, and notes it uses moderator permissions. However, it doesn't explicitly mention its relationship to sibling tools like nexus_pin_comment or nexus_remove_comment_like.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (lock against further interaction) and notes 'moderator permissions,' but it does not explicitly state when to use this tool versus alternatives like nexus_lock_comment_thread or nexus_hide_comment. There's no mention of conditions or exclusions, leaving the agent to infer from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds the return shape (JSON array of mod and file_details), but it does not disclose edge cases such as no-match behavior or rate limits. The added context is useful but modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler: the first states the lookup action and use case, the second states the return format. It is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only lookup tool, the description plus fully documented schema and rich annotations are sufficient. The agent knows what the tool does, how to fill required parameters, and what shape the result takes via the output schema. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both md5_hash and domain_name already have clear descriptions including constraints and examples. The tool description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Look up which mod and file on Nexus matches a file's MD5 hash') and the resource (Nexus mod/file by MD5). It is specific enough to be understood, but it does not explicitly differentiate from nearby siblings such as nexus_get_file_hash or nexus_get_file_hashes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(useful to identify an installed file)' gives a clear intended use case. It does not name alternative tools or state when not to use it, so it falls short of explicit when/when-not guidance but still provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond annotations: it discloses the rate-limit pool ('Consumes the v2 GraphQL pool, NOT the v1 REST rate-limit quota') and the exact return shape ('JSON {trackUser: {success}} or an error string'). No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and purpose is front-loaded in the first sentence. The returns block is slightly redundant with the existing output schema, but the 'or an error string' detail earns partial credit and the overall structure is tight with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 1-parameter tool with an output schema and annotations covering idempotency and safety, the description covers purpose, quota behavior, and return shape — nearly everything needed to call it correctly. Minor gaps remain: it does not cross-reference nexus_untrack_user as the reversal, nor describe failure behavior for a nonexistent user, but these are small for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single user_id parameter already has a clear description ('Nexus Mods member ID to track for updates') plus a minimum constraint. The description adds nothing about parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Start tracking a user') and clarifies the meaning of tracking with the parenthetical '(get notifications about their new mods)'. This distinguishes it from siblings like nexus_track_mod (tracking a mod) and nexus_untrack_user (the inverse operation) without needing to open either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it — when the agent wants user-level update notifications — and the resource type implicitly separates it from nexus_track_mod. However, it never names the natural alternative (nexus_untrack_user) or explicitly states when not to use it, so routing guidance is left to inference rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the core safety profile is covered. The description adds the v2 GraphQL channel and the returned fields (id, status, closureReason, closedAt), but it does not explain irreversibility or ownership requirements beyond 'your collection.' There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: one sentence states the operation and one block states the return shape. There is no filler or redundant repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with full schema coverage, a return shape, and safety annotations, the description provides enough context to invoke the tool correctly. It could be stronger with explicit authentication/ownership guidance, but 'your collection' already signals the main prerequisite.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters and the closure_reason enum is self-explanatory. The description introduces no additional parameter-level meaning, which is acceptable given the full schema coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Close') on a specific resource ('a bug report on your collection') and distinguishes it from the many collection-related sibling tools. The 'via v2 GraphQL' qualifier and 'your collection' scope make the operation concrete and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening phrase clearly indicates when to use the tool: when closing a bug report on the authenticated user's own collection. No sibling tool appears to duplicate this action, so an explicit alternative is not necessary, though the description does not spell out exclusions or prerequisites such as collection ownership.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a non-read-only, non-idempotent, non-destructive action. The description adds a useful permission caveat and describes the success/error return shape. However, it does not disclose broader side effects, such as whether the tag becomes immediately visible or how duplicates are handled, which would be valuable given openWorldHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core action, then follows with a concise return-value note. It contains no filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation, the description and schema together provide enough information: required name, optional attributes, permission caveat, and return shape. Minor gaps remain around usage guidance versus related tag tools and more precise permission requirements, but these are not severe enough to impede correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all five parameters with clear descriptions, so schema coverage is 100%. The tool description adds no additional parameter-level meaning, which fits the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action, 'Create a new tag,' on a specific resource, and identifies it as the v2 GraphQL operation. This clearly distinguishes it from sibling tools like nexus_update_tag and nexus_discard_tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'new' clearly signals this is for creating tags, not updating or discarding existing ones. It also provides a relevant precondition by noting moderator permissions may be required. It does not explicitly name alternatives, but the purpose is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that this is a presigned-URL request and that the response contains {url, uuid}, which is useful. Annotations already disclose readOnlyHint, idempotentHint, openWorldHint, and non-destructiveness, so the bar is lower; the description does not contradict these but also does not reveal additional behavior such as URL expiry, upload method, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the operation and resource, and the second gives the response shape. No filler or redundant material exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only request tool with annotations and an output schema, the description is largely sufficient. It clearly identifies the purpose and return shape; a slight gap is that it does not explain how the returned URL/uuid fit into the broader collection-revision workflow or compare with the sibling media-upload tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and schema description coverage is effectively complete, so there are no parameter semantics to document. Per the 0-param baseline, a score of 4 is appropriate; the description correctly implies there is nothing for the caller to supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb ('Request'), a concrete resource ('presigned URL for uploading a collection revision bundle'), and protocol context ('v2 GraphQL'). This differentiates it from the sibling media-upload tool by naming the specific bundle type, so an agent can identify it without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The resource mention makes the intended use clear: this is for obtaining an upload URL for collection revision bundles. However, there is no explicit guidance about when not to use it or how it relates to alternative upload/request tools such as nexus_request_media_upload_url; the usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent/non-destructive safety, so the description adds the return envelope {totalCount, _returned, nodes} and the explicit pagination behavior offset += _returned. It also flags the 'legacy bridge' path, a useful caveat beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sections with no filler: a purpose sentence followed by return format and pagination. The most decision-relevant information (legacy bridge, pair-based lookup) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with a 100% covered input schema, an output schema, and safety annotations, the description covers the essential usage loop. It doesn 't discuss limits on ids length or deprecation status of the legacy bridge, but those are minor gaps given the structured context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already documents all three parameters with 100% coverage, so the description doesn't need to restate them. It adds value by specifying the pagination contract (offset += _returned), which connects count/offset to the response's _returned field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the operation ('Get mods'), the resource ('mods by (gameId, modId) pairs'), and the API path ('legacy bridge (v2 GraphQL)'). This is specific enough to distinguish it from single-mod getters like nexus_get_mod while keeping the legacy-vs-batch nuance visible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to choose this tool over alternatives such as nexus_get_mods_batch or nexus_get_mod_v2. The only usage instruction is the pagination loop, which is a how-to, not a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral detail by specifying the exact return structure (JSON dict mapping version to list of HTML strings), which informs the agent about the output format beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single clear purpose sentence followed by a 'Returns' section that explains the output format with an example. There is no unnecessary verbosity, and every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the rich schema, and the presence of an output schema, the description is nearly complete. It provides the return format and purpose. Minor gaps like error handling or edge cases (e.g., non-existent mod) are not mentioned, but these are not critical for a simple read operation, so a score of 4 is reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (mod_id and domain_name) fully described. The description adds no additional parameter information, but since the schema already documents them thoroughly, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves changelog history for a single mod with the specific verb 'get' and resource 'changelog history'. The scope 'for one mod' differentiates it from similar tools like nexus_get_mod or nexus_get_mod_files, and the example return format further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when changelog history is needed, but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. There is no guidance on prerequisites or context, leaving the agent to infer based on the name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds value by specifying the return shape: 'JSON {id, name, adult, global, taggablesCount, category, games}'. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one clear purpose statement followed by a concise return-field list. Every sentence earns its place and there is no repetitive filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only single-tag retrieval with one well-documented parameter and an output shape provided, the description is largely sufficient. It could be slightly more complete by pointing to list endpoints for browsing tags, but nothing critical is missing for invoking this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter tag_id is fully documented in the schema as 'Tag ID.' with a minimum of 1, so the schema already covers the meaning. The description does not add additional semantic detail about the parameter, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 a single tag by ID (v2 GraphQL).' This distinguishes it from the plural list tool 'nexus_get_tags_v2' by explicitly saying 'a single tag', so an agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by ID' phrasing implies the tool is for retrieving one tag when an ID is known, but the description does not explicitly explain when to use this tool versus alternatives like nexus_get_tags or nexus_get_tags_v2. Usage context is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read, idempotent, non-destructive mutation. The description adds useful behavioral context beyond annotations: the permission requirement and the return shape ('JSON {commentThread: {id, lockedAt}} or an error string'). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: purpose, prerequisite, and return value are each presented in a single line. Every sentence earns its place, and the most important action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, non-destructive mutation with an output schema, the description covers the essential operational details: what is locked, who may do it, and what the response looks like. It could be slightly more complete by explicitly distinguishing thread locking from comment locking, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter's description ('Comment thread ID to lock.') fully explains its meaning. The tool description does not add significant parameter detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Lock') and resource ('a comment thread'), with a clarifying example ('e.g. a mod's comments page'). It is unambiguous and distinguishes the thread-level operation from sibling tools like nexus_lock_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context and a prerequisite ('Requires moderator permissions or thread ownership'), but it does not explicitly say when to choose this tool over alternatives such as nexus_lock_comment, hide_comment, or moderation-clear tools. Usage is implied rather than explicitly scoped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a non-read-only, non-destructive, idempotent operation. The description adds meaningful behavioral context beyond those annotations by stating the collection is hidden from public listings but the URL is kept, and by noting the response shape ('JSON {success} or an error string').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core action and effect appear in the first sentence, and the return-format note is minimal. No filler or redundant wording is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation with an output schema and annotations covering idempotence and destructiveness, the description is reasonably complete. It explains the key effect and return behavior, though it does not mention any ownership or authorization requirements, which may be contextual prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter collection_id is already described as 'Collection ID.' with a minimum of 1. The description does not add further semantic detail about the parameter, which is acceptable because the schema carriers the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Unlist'), identifies the resource ('a collection'), and clarifies the effect ('hide from public listings, keep URL'). This clearly distinguishes it from similar collection tools like nexus_list_collection and nexus_discard_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case is implied by the description: use this when a collection should be hidden from public listings while retaining its URL. However, it does not explicitly name alternatives or state when not to use it, such as when relisting is desired via nexus_list_collection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds return format ('JSON {success} or an error string') which is useful, but the annotations already cover safety flags (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description does not disclose potential side effects, permission requirements for targeting other users via user_id, or error conditions beyond the generic error string. It adds some value but not deep behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences. The purpose is front-loaded, and the return statement is a single line. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with an output schema (indicated by 'Has output schema: true'), the description covers the essential behavior and return format. The optional user_id with its 'Omit for the current user' default is documented in the schema. Minor omissions (e.g., prerequisite authentication) are likely assumed and not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (about and user_id) already documented in the input schema. The description adds no additional parameter meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and resource ('a user's About Me profile text') and specifies it uses v2 GraphQL, distinguishing it from other update tools like nexus_update_country or nexus_update_preferences. This is specific enough for an agent to identify the tool's purpose without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context—this tool is specifically for updating About Me text—but does not mention alternatives or explicit exclusions. Since it's the only tool for this purpose among many siblings, the context is sufficient for routing, though it lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly=false, idempotent=false, and destructive=false, so the description adds value by disclosing the actual request type (Apollo Upload multipart), the encoding requirement (base64), and the return shape (JSON attachment object or error string). This goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence earns its place. The return format is clearly separated and easy to parse, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an upload tool with a rich schema and output schema, the description covers the key workflow step (attachment upload before comment mutations) and the expected response. It could be more complete with explicit routing against sibling upload tools, but nothing critical is missing for invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents filename, mime_type, and content_base64. The description reinforces that content must be base64-encoded but does not add meaningful per-parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Upload'), a specific resource ('attachment'), and its intended use ('usable in comments'). It also names the exact transport mechanism ('v2 GraphQL multipart spec'), which separates it from other upload-adjacent tools like nexus_request_media_upload_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the attachment is uploaded before being referenced in comment mutations, giving some contextual guidance. However, it does not explicitly state when to choose this tool over alternatives, nor does it mention any exclusions or prerequisites such as authentication or file-size limits.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it uses the v2 GraphQL API, is quota-free against the v1 pool, and returns a specific JSON shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded and the return format is useful, but the description is somewhat redundant: 'Backed by the v2 GraphQL API' repeats the first sentence, and 'quota-free on the v1 pool' repeats the earlier rate-limit statement. It is concise overall, but not maximally tight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, read-only tool with full schema coverage, rich annotations, an output schema, and a clear sibling comparison, the description provides all information an agent needs to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both parameters, including the important note that domain_name is a lowercase URL slug, not the display name. The description does not need to repeat parameter semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: 'Get the complete file list of a mod via v2 GraphQL.' It also explicitly distinguishes itself from the sibling tool nexus_get_mod_files by noting it returns the same data but from v2, so an agent can immediately tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names nexus_get_mod_files as the alternative and gives a concrete selection criterion: the v2 API does not consume the v1 REST rate-limit quota. It does not explicitly state when not to use this tool, but the usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context beyond those hints: it specifies the exact result count ('10'), the recency criterion ('most recently added'), and that the return value is an array of mod info objects. No behavioral claims contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core action and result count, then appends the return type. Every word contributes meaningful information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one fully documented parameter and a provided output schema, the description is complete: it names the operation, scope, count, and return shape. Nothing else is needed for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter domain_name 100%, including an example and a 'NOT the display name' clarification. The description adds little beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a specific resource ('the 10 most recently added mods for a game'), and the expected shape ('array of mod info objects'). The word 'added' distinguishes it from sibling tools like nexus_get_latest_updated and nexus_get_trending, so an agent can select it correctly 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is clearly implied: when you want the 10 most recently added mods for a specific game. However, the description does not explicitly name alternatives or state when not to use this tool, leaving the agent to infer the distinction from 'added' versus sibling names like 'updated' or 'trending'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/openWorld annotations, the description warns that the description field contains literal '<br />' tags requiring rendering or stripping, and clarifies the API backend is v2 GraphQL and does not consume v1 REST quota. It also discloses the exact return shape. This is useful behavioral context on top of the annotations, though auth/error behavior is not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into three tight sections: purpose/contrast, backend/rate-limit note, and return structure. Every sentence contributes, and the return JSON block is concise despite its detail. It earns its length for a data-rich tool, though it could be slightly shorter without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and a detailed return description, the agent has everything needed to call the tool and interpret results. The description covers the notable BBCode escaping quirk, required parameters are in the schema, and annotations cover safety. Missing items like authentication prerequisites and error cases are minor for a read-only getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both mod_id and domain_name are documented in the input schema, including an example for domain_name. The description adds no additional parameter semantics beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get rich mod details via v2 GraphQL' and immediately enumerates the distinguishing payload: full description (raw BBCode), tags, requirements, and complete file list. It explicitly contrasts with v1 REST ('none of which v1 REST exposes'), making the tool's purpose and scope unambiguous even among many siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent when to prefer this tool: when rich fields like BBCode description, tags, requirements, or full file list are needed, and when avoiding the v1 REST rate-limit quota matters. It does not explicitly name an alternative tool like 'use nexus_get_mod for basic info', so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds only a 'v2 GraphQL' note and the returned JSON shape; with an output schema present, these add limited behavioral context beyond what structured fields already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the purpose in the first sentence and then gives the return shape. Every sentence contributes useful information, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only, one-parameter tool with a rich output schema and strong annotations, the description is complete. It correctly identifies the resource, the user scope, and the return structure; nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single parameter account_id is documented as 'Account ID.' The description does not add additional semantic detail about the parameter beyond reinforcing that it refers to the user whose mods are being listed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List a user's mods that opted into Donation Points (v2 GraphQL).' This clearly distinguishes the tool from sibling list-type tools like nexus_get_tracked_mods or nexus_get_favourite_games by the unique DP-opt-in qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you need the DP-opted-in mods for a user. It does not explicitly compare against alternatives or state exclusions, but the intended use is unambiguous given the precise resource description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/write nature, idempotency, and destructiveness. The description adds meaningful context beyond annotations by revealing the v2 GraphQL quota pool behavior and the exact return shape: JSON {giveKudos: {success}} or an error string. This does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose first, then the quota distinction, then the return format. Every sentence contributes useful information and there is no filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter action with annotations covering idempotency and destructiveness, the description is complete. It states the action, the API/rate-limit context, and the expected response format. Nothing essential is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with the user_id parameter described as 'Nexus Mods member ID to give kudos to.' The description adds no additional parameter-level detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Give kudos to a user via v2 GraphQL.' It clearly identifies the action, the target, and the API version, and it is distinct from sibling tools like nexus_remove_kudos, which perform the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever the agent needs to give kudos to a user. It also provides a selection criterion by stating it consumes the v2 GraphQL pool rather than the v1 REST quota. However, it does not explicitly mention alternatives or when not to use this tool, such as when retracting kudos via nexus_remove_kudos.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the rate-limit pool behavior ('Consumes the v2 GraphQL pool, NOT the v1 REST rate-limit quota') and the expected return shape. This adds useful behavioral context that is not present in the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and every sentence earns its place: action, quota note, and return format. There is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, idempotent, non-destructive operation, the description is fully sufficient. The annotations cover mutation/idempotency/safety, the schema covers the parameter, and the description covers behavior and return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents comment_id with 100% coverage, including a clear description. The tool description adds no new param-level semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove'), a precise resource ('your like from a comment'), and the API channel ('v2 GraphQL'). This clearly distinguishes it from sibling operations like nexus_like_comment, nexus_create_comment, and nexus_discard_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
That the tool is for removing the caller's own like is clear, so the usage is implied. However, there is no explicit guidance on when to choose this over the sibling nexus_like_comment, nor any mention of prerequisites beyond having a like to remove.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as non-read-only, idempotent, and non-destructive. The description adds valuable behavior: partial-update semantics ('only provided fields are changed; omitted fields stay as-is') and the exact success/error return shape, which is not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences lead with the action, state the critical partial-update rule, and give the return contract. No filler; each sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter all-optional update with a full schema, the description is complete: it identifies the affected resource, explains how parameters behave when omitted, and specifies the response shape. Annotations cover idempotency and destructiveness, so no essential calling context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter has a description, so the baseline is 3. The description earns an extra point by clarifying that absent parameters are ignored rather than reset to null despite the schema's default: null, which prevents a likely misinterpretation of the partial-update behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and a precise resource ('the current user's Donation Points preferences') and notes the GraphQL v2 interface. This clearly sets it apart from the sibling getter nexus_get_user_donation_preferences and from generic nexus_update_preferences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool instead of sibling update/preference tools. It doesn't mention that reading preferences should use nexus_get_user_donation_preferences or that generic settings belong to nexus_update_preferences; the only cue is the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description reveals the rate-limit pool trait ('Consumes the v2 GraphQL pool, NOT the v1 REST rate-limit quota') and the exact return shape ('Json {addFavouriteGame: {success}} or an error string'). It also aligns with annotations: readOnlyHint=false and destructiveHint=false are consistent with an add operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sections, each earning its place: purpose, pool/rate behavior, and return format. The most important information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The definition covers the action, API-pool behaviour, return format, and parameter provenance. Minor gaps exist around authentication prerequisites or duplicate-favourite edge cases, but for a single-parameter idempotent mutation these are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter game_id is already well-described in the schema as coming from nexus_search_games / nexus_get_game. The description adds no parameter-level guidance, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Add a game to your favourites via v2 GraphQL.' This clearly identifies the action and differentiates it from siblings like nexus_remove_favourite_game and nexus_get_favourite_games by naming the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives relevant context by noting the v2 GraphQL pool and explicitly saying it does NOT consume the v1 REST rate-limit quota. This helps an agent choose it for v2-pool operations, though it does not explicitly compare against sibling tools like remove/get favourite games.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover non-read-only, non-idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the ownership requirement and the return contract 'JSON {success, changelogId} or an error string', which clarifies failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences plus a one-line return value. The primary action and ownership constraint are front-loaded, and the return information is useful without redundancy given the output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters with full schema coverage, existing annotations, and an output schema, the description covers the action, ownership prerequisite, and return contract. It is complete enough for correct invocation, though it does not explicitly mention related operations like nexus_update_changelog.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are already documented. The description maps conceptually (collection revision -> revision_id, changelog entry -> description) but adds no extra format, constraints, or examples beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action 'Create a changelog entry' with a specific target 'for a collection revision', plus the ownership constraint 'must own it'. It clearly differentiates from the sibling nexus_update_changelog (create vs update) and read-only changelog tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes clear when to use the tool: to create a changelog entry for a collection revision, and it provides a key prerequisite (ownership). It doesn't explicitly name alternatives or when-not-to-use, but the create-vs-update context is clear enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds useful behavioral detail beyond annotations: mods_json replaces the mod list, omitting it leaves the revision unchanged, and the return is a success/error JSON object. Annotations already cover readOnly/idempotent/openWorld, so the description only needs to add behavior specifics; it does, though it does not explain how the create-vs-update decision is made.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well structured: purpose first, then the key mods_json behavior, then the return contract. Every sentence earns its place, with no fluff or unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage, an output schema, and annotations describing safety/idempotency, the description does not need to repeat return details or every parameter. It covers the core behavioral contract well; the main gap is the exact condition that determines whether a new draft revision is created versus an existing draft updated, but this is partially inferable from the tool name and first sentence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds real meaning for the two most nuanced params by stating that mods_json replaces the mod list and omission keeps it unchanged, while collection_data_json is an alternative full-payload path. This goes beyond the schema field descriptions, although most overrides are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear, specific action: create or update a draft collection revision, and identifies the API version (v2 GraphQL). The resource is unambiguous and the wording separates it from publish/discard/retract-revision siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the central parameter choice—pass mods_json/collection_data_json to replace mods, omit mods_json to leave them unchanged—but does not explicitly distinguish this tool from overlapping siblings like nexus_update_revision or say when one should be preferred over the other. The usage context is implied by the name and opening sentence, but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds value beyond these: it clarifies the destruction is a soft-delete (not permanent), discloses the ownership prerequisite ('must own it'), and states the return shape ('JSON {success} or an error string'). This is meaningful supplementary context for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 30 words and front-loaded: core meaning first, then destructive warning with alternative, then return format. Every sentence earns its place — no filler, no restatement of schema fields, and the most decision-relevant information (destructive + prefer unlist) appears immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param destructive tool with full schema coverage, annotations covering the safety profile, and an output schema, the description is strong. It covers purpose, ownership, destructive nature, preferred alternative, and return format. The only minor gap is whether the soft-delete is recoverable and how — no restore sibling appears in the list, leaving the reversibility ambiguity unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — both collection_id and reason have descriptions ('Collection ID.' and 'Discard reason.'). The tool description adds no parameter-specific meaning beyond the schema, so the baseline of 3 applies. The description does imply reason is required by the destructive context, but the schema already marks both as required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Discard (soft-delete) an entire collection'), adds the ownership constraint ('must own it'), and clarifies the implementation ('via v2 GraphQL'). It explicitly differentiates from sibling nexus_unlist_collection by naming it as the preferred alternative. An agent can immediately understand both what this tool does and how it differs from nearby tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: 'Prefer nexus_unlist_collection' tells the agent this tool is not the default choice, and the DESTRUCTIVE warning indicates it should only be used deliberately. It does not fully articulate the conditions under which discard IS the right choice versus unlist, but the preference signal plus destructive framing provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value beyond annotations by disclosing the rate-limit behavior ('does NOT consume the v1 REST rate-limit quota') and listing the exact JSON return fields. This is useful operational context for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary action. The rate-limit note is valuable and the return field list is clearly structured. It is slightly redundant with the output schema, but it does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool, the description is complete: it states the purpose, API version, rate-limit implications, and return shape. Annotations cover safety/idempotency, and an output schema exists, so nothing needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with 'comment_id' described as 'Comment ID.', so the description does not need to add much. The description only reinforces that lookup is 'by ID' and does not add deeper semantic detail about the parameter, but the high schema coverage makes this acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get a single comment by ID', a specific verb plus resource, and identifies the API version ('v2 GraphQL'). This clearly distinguishes it from related tools like nexus_get_comment_thread or nexus_search_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this for a single comment lookup by ID, and it adds the practical note that it uses v2 GraphQL and does not consume the v1 REST rate-limit quota. It does not explicitly name alternatives or exclusions, but the purpose is specific enough that an agent can infer when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true; the description adds the exact return shape and notes the '_rl' rate-limit snapshot, which is useful behavioral context. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well ordered: action, use case, then returns shape. The Returns block is structured and front-loaded, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-param read-only tool with full schema and output schema, the description covers purpose, use case, and return shape. It could mention pagination/payload size concerns for 'all games', but the filter parameter mitigates that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both filter and include_unapproved are fully described in the schema. The description adds no extra parameter-level detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List all games on Nexus Mods with their domain_name, mod counts, and file counts.' It also names the key use case (finding the lowercase domain_name slug), which differentiates it from siblings like nexus_get_game and nexus_search_games.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear use case: 'Use this to find the correct lowercase domain_name slug for other tools.' This tells an agent when to choose this tool, but doesn't explicitly name alternatives or exclusions, so not a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable non-obvious context beyond annotations: it is backed by the v2 GraphQL API and does not consume the v1 REST rate-limit quota.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well front-loaded with the core purpose, then backend context, filtering, and return shape. The return block is arguably redundant given the output schema exists, but it is concise and useful for clarifying the exact payload.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, 100% schema parameter coverage, and an output schema present, the description is complete. It explains the API backend, rate-limit implications, filtering options, and return structure—everything an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all 4 parameters with types, defaults, constraints, and helpful notes such as the domain_name 'NOT the display name' example. The description mentions category and game filtering, but adds no meaningful parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Get Nexus Mods news articles', a specific verb and resource, and enumerates example content types. It is clearly distinct from all sibling tools, none of which target news retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates when to call this tool: whenever Nexus Mods news articles are needed, with optional category and game filtering. It does not explicitly name an alternative tool or exclusion case, but no direct news sibling exists in the provided list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the description doesn't need to repeat those. It adds valuable context by warning that privacy-restricted accounts may receive a permissions-related error, explicitly framing that as an API-side restriction rather than a tool failure. It also documents the expected JSON return structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and organized into a clear flow: what it does, how it relates to the summary tool, who should use it, a caveat about permissions, and the return shape. Every sentence adds useful information with no filler or unnecessary repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter read-only tool, the definition covers purpose, parameter selection context, return format, and an important error condition. The only notable gap is not addressing the sibling nexus_get_user_monthly_report_by_id, leaving the agent to infer why this tool should be preferred for a specific report.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already explains all three required parameters: account_id, year, and month. The description adds only marginal context, such as 'per-mod/per-game values' and 'chosen month,' but does not need to compensate for missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the download/upload numbers for ONE specific month via v2 GraphQL.' It explicitly distinguishes itself from nexus_get_user_monthly_summary by explaining that summary lists available months while this tool fetches actual per-mod/per-game values. This gives agents a clear identity for the tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly positions the tool as a companion to nexus_get_user_monthly_summary and tells the agent this is the right choice after choosing a month. It also gives a concrete use case: tracking your own mod's download history. However, it does not explicitly mention the similarly named sibling nexus_get_user_monthly_report_by_id or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), idempotent, and non-destructive. The description adds value beyond annotations by specifying the permission requirement and the return shape (JSON with comment id or an error string). No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short, focused sentences. It leads with the core purpose, follows with the prerequisite, and closes with the return format. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter mutation tool, the description is nearly complete: it names the action, the permission requirement, and the return format. It could additionally clarify what happens if the comment is already pinned, but that is a minor gap given the idempotency hint and the simplicity of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single parameter 'comment_id' is already documented as 'Comment ID to pin.' The tool description adds no further parameter-level semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Pin'), a specific resource ('a comment'), and a clear destination ('to the top of its thread'). This distinguishes it from sibling tools like nexus_unpin_comment, nexus_reorder_pinned_comments, and nexus_hide_comment without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a key precondition: 'Requires moderator permissions or thread ownership.' This gives clear context for when the tool can be used, though it does not explicitly name alternative tools or state when not to use it. That makes it slightly below the top tier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true; the description goes further by explaining the concrete irreversibility ('hard to undo'), the required ownership, and the mitigation route. It also states the return contract ({success} or error string), so the agent understands the non-local effects beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sections: purpose, consequence/undo, returns. No filler, and the most decision-relevant fact ('hard to undo', retract path) appears early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, output schema, and 100% schema coverage, the description covers ownership, effect, undo path, and return shape. It could more fully explain the optional collection_status values and edge cases, but nothing essential for a safe call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with descriptions, so the baseline is 3. The tool description adds no additional meaning about revision_id, collection_status, or has_adult_resources beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description names the exact verb and object ('Publish a draft collection revision'), adds the ownership precondition and API version, and contrasts the action with the undo sibling nexus_retract_revision. This clearly distinguishes it from the many collection-revision siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear precondition ('must own the collection') and states the consequence ('makes the revision publicly available') with an explicit pointer to nexus_retract_revision as the undo path. It does not enumerate when to choose publish over list/unlist or discard, but the 'hard to undo' warning plus sibling reference gives agents a usable decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds useful context beyond these: the ownership authorization requirement and the exact return shape (JSON {item: {__typename}} or an error string). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with each sentence carrying distinct information: operation scope, prerequisite, and return format. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with full schema coverage, annotations, and a stated return shape, the description covers the essential calling context. It could go slightly further by naming the comment-reordering sibling explicitly, but that is not necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a meaningful description with the location enum documented. The tool description does not add additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Reorder'), a resource ('collection images/videos'), and a clear scope. The parenthetical also distinguishes it from the sibling nexus_reorder_pinned_comments, which reorders comments rather than collection media.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear prerequisite ('Requires ownership of the parent collection') and scopes the operation to reorderable collection media. It does not explicitly name alternatives or exclusions, but the media-versus-comments distinction is evident from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable context: it notes the v2 GraphQL backend avoids v1 REST rate-limit quota, and provides pagination guidance ('Paginate with offset += _returned') and return structure. This goes beyond the annotation hints, but doesn't cover error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured: a one-line purpose, a clear differentiator, and a return format block. No wasted words; essential details are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 6 parameters and an output schema, the description is sufficiently complete. It covers the purpose, differentiator, return format, and pagination. It doesn't address edge cases like empty results or error handling, but those are minor for a read-only search operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description adds minimal additional meaning—it mentions partial names which relates to the mode enum, and explains pagination usage but not new per-parameter semantics. This aligns with the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search Nexus Mods users by username'. It specifies the verb (Search), resource (users), and parameter (username). It also distinguishes itself from sibling nexus_get_user_v2 by noting partial name support, which helps an agent differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts with nexus_get_user_v2 ('Unlike nexus_get_user_v2 this supports partial names'), giving a clear condition for preferred use. It also mentions the API version and rate-limit advantage. However, it does not list when not to use it or mention other alternatives like nexus_get_user_by_name, so it's not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, it discloses the authorization model and the result shape (JSON with {comment: {id}} or an error string). Annotations already mark this as a non-read, non-destructive, idempotent mutation, so the description adds useful context without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short lines, front-loaded with the core verb and resource. The permission and return-format notes are useful and there is no filler. 'via v2 GraphQL' is slightly redundant with the title but not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one well-documented parameter, an output schema, and annotations covering idempotency and destructiveness; the description adds the missing auth condition and error behavior. Nothing required to select or invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; comment_id is already described as 'Comment ID to unpin' with type and minimum. The description adds no new parameter-level detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete action—'Unpin a previously pinned comment'—and names the mechanism (v2 GraphQL). This clearly distinguishes it from the sibling nexus_pin_comment and from other mutable comment actions like hide/lock.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the permission prerequisite ('requires moderator permissions or thread ownership') and implies the precondition that the comment must already be pinned. It does not explicitly enumerate when to prefer alternatives, but the action and sibling names make the choice reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the ownership authorization requirement and the concrete success/error return shape, which are useful behavioral details beyond the annotations. It does not over-explain side effects, but the update semantics are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with the core operation front-loaded. It includes the essential capability, an ownership caveat, and the return shape without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter mutation with a stated return contract and ownership prerequisite. An output schema exists and annotations cover idempotency and non-destructiveness, so the agent has enough context to invoke this tool correctly. Minor gap: no explicit statement that this is for modifying an existing entry versus creating a new one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds one meaningful semantic beyond the schema: the changelog_id must refer to an entry owned by the caller. The description param is adequately described as 'New changelog text.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update'), a specific resource ('existing changelog entry'), and a key precondition ('must own it'). 'via v2 GraphQL' plus the return shape removes ambiguity and differentiates it from read/create changelog tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when this tool is appropriate: updating a changelog entry the caller owns. However, it does not explicitly contrast with nexus_create_changelog or the read-only changelog retrieval tools, so the agent must infer the when-not-to-use boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds useful behavioral detail: partial update semantics ('Only the provided fields are changed; omitted fields stay as-is') and the return shape. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a clear one-sentence purpose, one sentence covering partial-update semantics, and a brief return specification. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficiently complete for a mutation tool with 3 parameters, annotations, and an output schema. It covers the core behavior, ownership requirement, and return value, though it does not enumerate specific error cases or alternative sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that omitted optional fields are preserved. This is especially valuable because adult_content and installation_info are nullable with defaults, making behavior non-obvious.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update'), a specific resource ('collection revision's metadata'), and a key ownership constraint ('must own it'). It is clearly distinct from sibling tools like nexus_create_or_update_revision, nexus_publish_revision, and nexus_retract_revision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: update metadata on a revision you own. It does not explicitly mention alternatives or when not to use this tool, such as when a revision may not exist and should be created instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this destructive and non-read-only. The description adds useful behavioral context by stating that moderator permissions are required when targeting another user, and by summarizing the return shape as JSON success or an error string. This goes beyond the structured fields without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the core action appears in the first sentence, the key permission requirement in the second, and the return format in the third. Every sentence earns its place, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with annotations indicating destructive behavior and an output schema present, this is complete. It identifies the target, the permission requirement, the optional current-user behavior, and the return shape. An agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: user_id already has a clear description and default null. The description adds the permission nuance when targeting another user, but does not significantly extend the schema's parameter guidance, so the high-coverage baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Block'), a clear resource ('a user's mods'), and the precise effect ('from earning Donation Points'). It clearly distinguishes this from the sibling 'unblock mods from earning dp' tool, and the optional user_id context reinforces the target scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: targeting another user requires moderator permissions, while omitting user_id means the current user. It does not explicitly name the unblock sibling as an alternative, so it misses the top score, but it provides enough context to use the tool correctly in the main scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds behavioral context by specifying the download requirement and cooldown (TOO_SOON_AFTER_DOWNLOAD), and it documents the exact return JSON. This goes beyond what annotations provide, without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it states the purpose in one sentence, then lists constraints and the return format in a clear, scannable way. No unnecessary words, and the main action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation, the description covers the purpose, prerequisites, constraints, and return format. The schema covers all parameters, and annotations cover safety aspects. Nothing essential for an agent to invoke this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes all three parameters (mod_id, version, domain_name) with clear descriptions, achieving 100% schema coverage. The description does not add parameter-specific meaning beyond what the schema already provides; it only restates the version example. Since schema coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action: 'Endorse a mod on behalf of the authenticated account.' This is a specific verb and resource, and it clearly differentiates from sibling tools like nexus_abstain_endorsement which performs the opposite action. The inclusion of constraints (downloaded mod, cooldown) further clarifies the operation's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear prerequisites: the account must have downloaded the mod and wait 15 minutes, implying when this tool is appropriate. However, it does not explicitly mention alternatives (e.g., nexus_abstain_endorsement for abstaining) or when not to use this tool. Thus it gives clear context but lacks 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint false). The description adds that it returns a JSON list with specific fields and identifies it as v2 GraphQL, but does not mention autthentication requirements or rate limits. This is acceptable given annotation coverage, so average score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states the action, the second lists the return fields. The purpose is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A zero-parameter, read-only tool with output schema present. The description provides enough detail about scope and return structure for an agent to invoke it correctly without further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%. With no params to document, a baseline of 4 is appropriate since no param semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'List the authenticated account's registered API applications' and notes v2 GraphQL. This clearly differentiates it from other nexus_* tools because the resource is unambiguous as API applications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No alternatives are explicitly named, but the account-scoped scope clearly implies this is the tool for viewing the authenticated user's own API applications. Since no sibling tool serves the same function, missing exclusion guidance is not a practical gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description does not contradict these. It adds useful behavioral context by explaining the purpose of blocked tags and specifying the returned fields, which goes beyond the raw annotation metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear action statement, a brief functional explanation, a related-tool hint, and a succinct return format. Every sentence contributes useful information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional boolean parameter and an output schema, the description is complete. It explains the resource, the user scope, the semantic effect of blocked tags, and the return shape, leaving no material gaps for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter exclude_adult fully described in the schema. The description does not add additional parameter-level meaning, but none is needed because the schema already handles it, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the current user's blocked tags', which clearly identifies this as a read operation targeting the user's blocked-tag list. It distinguishes itself from sibling tools like nexus_get_tags and nexus_get_tags_v2 by emphasizing 'blocked' and 'current user's' tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: blocked tags hide matching mods/collections from searches, so an agent knows this tool is relevant when working with the user's tag-blocking preferences. It also suggests related tools for finding tag IDs, though it does not explicitly state when not to use this tool or name direct alternatives for listing all tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is well covered. The description adds the exact return fields and the single-result scoping, giving additional contextual value without contradicting any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, front-loaded with the operation, and includes only a concise return-shape block. Each sentence carries necessary information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only, idemopotent getter with an output schema and rich annotations, the description is complete. It names the resource, the input, and returned fields; no additional context is necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: category_id is already documented as 'Category ID.' The description does not add deeper semantics beyond 'by ID,' so it does not exceed the baseline expected when the schema already covers the parameter fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 a single collection category by ID.' This clearly distinguishes it from list tools like nexus_get_categories and from related tag/tag-category lookup tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use this when you need exactly one collection category identified by category_id. It does not explicitly mention when not to use it or name an alternative list operation, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the specific response shape and the 'unread' filter, but does not disclose details like authentication requirements or potential absence of data. With strong annotation coverage, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in one sentence, followed by a compact and precise return payload listing. Every element earns its place, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with rich annotations and an output schema, the description is complete. It tells the agent what the tool returns and for whom, leaving no practical ambiguity for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the input schema is already fully unambiguous. The description appropriately avoids inventing meaningless parameter guidance. The baseline for zero-parameter tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a precise resource ('the current user's unread moderation warnings and global notices'), and clearly distinguishes it from the many read-oriented sibling tools. The inclusion of '(v2 GraphQL)' adds version specificity without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this when you need the authenticated user's unread moderation warnings and global notices. It does not explicitly name alternatives or exclusions, but the resource is unique enough among the sibling tools that an agent can infer when to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
注释已声明readOnlyHint=true和destructiveHint=false，因此描述无需重复安全概况。它增加了有价值的行为上下文：URL是短时有效的、不应缓存、返回镜像列表且第一个位置是首选。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
描述简短且前置了核心目的，然后以有用的结构呈现认证要求，最后以返回格式和缓存警告收尾。每个句子都贡献了操作所需的信息，没有冗余。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
对于具有5个参数、账户特定行为和现有输出schema的工具，描述覆盖了所有关键方面：用途、认证变体、必需参数来源、返回结构以及缓存限制。没有遗漏任何关键信息。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
输入schema的覆盖率为100%，参数描述已经解释了key和expires的来源、required条件、domain_name格式以及数值ID。描述在参数语义方面没有显著增加超出schema的内容，因此基线3是合适的。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
明确且具体的动词+资源：从Nexus CDN获取mod文件的短时下载URL。这将其与返回文件信息或直接下载的兄弟工具区分开来，并说明了它是什么（URL、非文件内容）。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
提供了明确的实用条件：高级账户可省略key/expires，非高级账户必须从.nxm链接提取。虽然没有明确命名替代工具或'何时不使用'，但前提条件和所需参数来源已清晰陈述。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds a valuable behavioral detail beyond those annotations: this call consumes the v2 GraphQL pool rather than the v1 REST rate-limit quota, which materially affects rate-limit planning. It also confirms the return shape is a JSON array.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the main purpose appears in the first sentence, followed by a single high-value rate-limit note, then a concise return-format list. No filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple, parameterless read-only tool with supportive annotations and an output schema, the description provides enough context: what is returned, which GraphQL pool is used, and that it operates on the authenticated user's data. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema fully covers parameter needs. The description's mention of the returned fields is not about parameters, but no parameter documentation is needed here. Baseline 4 for a zero-parameter tool is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: retrieve the authenticated user's favourite games. It also identifies the API version (v2 GraphQL), making it easy to distinguish from sibling tools like nexus_get_games, nexus_add_favourite_game, and nexus_remove_favourite_game.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope is clear: this is for the authenticated user's favorite games. However, the description does not explicitly name alternatives, state when not to use this tool, or provide exclusion criteria versus related game-listing tools. Usage is mostly implied rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description's extra context is valuable rather than redundant. It adds that the API avoids the v1 REST rate-limit quota and documents the return shape: a JSON game object or an error object for unknown domains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence adds useful information: what the tool returns, the API-backend distinction, and the error behavior. There is no redundant or filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single well-documented parameter, rich annotations, and an existing output schema, the description covers all essential aspects: what it does, what it returns, and how it behaves on unknown domains. No critical information is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter, clearly explaining that domain_name is a lowercase URL slug and not a display name. The description adds no further parameter-specific semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 rich game details via v2 GraphQL') and lists concrete data points it returns, such as mod/download/collection counts, genre, forum URL, and Vortex support. It also distinguishes itself from the v1 REST-based sibling by emphasizing the v2 GraphQL backend and rate-limit behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly signals when this tool is preferable by noting it does NOT consume the v1 REST rate-limit quota, giving the agent a strong reason to choose it over v1 alternatives. It does not explicitly name an alternative or state when not to use it, so it stops short of a full when/when-not guide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and idempotentHint, so the description's job is lighter. It adds meaningful behavioral context by documenting the JSON shape, the update-chain relationship, and the category_id mapping, which an agent needs to interpret results. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the purpose, and uses a short structured return block for the update chain and category mapping. Every sentence carries information and no filler is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation, the description plus annotations and output schema cover the required inputs, the returned shapes, and category semantics. No critical detail needed to invoke the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: domain_name, mod_id, and category are already documented in the schema. The description adds category-id semantics for interpreting results, but does not add parameter-level usage detail beyond the schema, so it meets the baseline without exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List all files attached to a mod', then enumerates return fields (versions, sizes, upload dates, update chain). This clearly distinguishes it from sibling tools like nexus_get_file_info or nexus_get_download_link, which target individual files or downloads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'List all files attached to a mod' supplies clear when-to-use context, and the return details ('update chain') signal a bulk listing use case. It does not explicitly contrast with alternatives or state exclusions, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses that it uses v2 GraphQL and does NOT consume the v1 REST rate-limit quota—an important behavioral trait for API quota management. It also documents the return structure as a JSON list of tag objects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, information-dense sentences. The primary purpose is front-loaded, followed by the rate-limit distinction and the return format. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only tool with a full input schema, rich annotations, and an output schema listing return fields, the description covers purpose, quota behavior, and use case. Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all three parameters. The description does not add meaning beyond the schema, staying at the baseline rather than providing extra parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('mod tag taxonomy of a game'), and the transport ('v2 GraphQL'). It also differentiates from related endpoints by noting it does NOT consume v1 REST rate-limit quota, which helps distinguish it from sibling tools like nexus_get_tags_v2.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names a concrete use case: 'Useful to build tag filters for nexus_search_mods.' This gives clear context for when to invoke the tool, though it does not explicitly rule out alternatives or name sibling tools for exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive, so safety is covered. The description adds useful behavior beyond annotations by disclosing that results are server-cached for 5 minutes and specifying the returned timestamp fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence purpose, followed by a tight return-type block, cache note, and use case. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read-only endpoint with full schema documentation, annotations, and an output schema, the description supplies the missing behavioral context: caching, epoch timestamps, and a concrete use case. An agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both period and domain_name have detailed descriptions including format, example, and enum values. The tool description adds no additional parameter-level meaning beyond restating the concept of a game and time window, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: get all mods for a specific game whose files or activity changed within a given time window. It clearly identifies the resource (mods), the game scope via domain_name, and the time-window filter, which distinguishes it from generic latest/trending endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear intended use case ('Useful to check if your own mod page saw activity') and scopes the call by game and period. It does not name sibling alternatives or explicitly say when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds current-user scoping and the v2 GraphQL implementation detail, but much of the return-field information is likely already captured by the output schema, and no additional behavioral traits such as auth needs or rate limits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence states the purpose, one compact block lists return fields, and one short sentence names the editing counterpart. There is no filler or redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only tool with a rich annotation set and an output schema, the description covers everything needed for correct invocation: the resource, the current-user scope, the returned fields, and the related mutation tool. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%, so the baseline is 4. The description usefully reinforces that the target is the current user, which is the only meaningful parameter-like information needed here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Get the current user's Donation Points donation preferences (v2 GraphQL).' It lists the returned fields and names the companion update tool, which clearly distinguishes it from the many nexus_get_* and preference-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as read-only retrieval and explicitly routes editing to nexus_update_user_donation_preferences with 'Edit with...'. It does not explicitly contrast with nexus_get_preferences or state when not to use this tool, so it stops short of the strongest when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: it discloses the rate-limit pool consumed and the exact return shape ('JSON {likeComment: {comment}} or an error string'). Annotations already cover idempotence and non-destructiveness, so the additional rate-limit and response details are valuable without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the core purpose appears in the first sentence, followed by the rate-limit caveat and return format. Every sentence earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter action with an output schema and annotations already covering safety traits, the description is complete. It includes the rate-limit distinction, the return format, and the GraphQL variant, leaving no obvious gap for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameter semantics with a clear description ('Comment ID to like') and a minimum value constraint. The tool description adds no additional parameter meaning, but because the schema is complete, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the exact action ('Like a comment') and the API variant ('v2 GraphQL'), making the tool's purpose immediately clear. It also distinguishes itself from related siblings like nexus_remove_comment_like through the verb 'like' rather than 'remove'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly communicates a relevant selection constraint: this uses the v2 GraphQL pool rather than the v1 REST quota. It does not explicitly name alternatives or state when not to use the tool, but the action is unambiguous and the rate-limit context helps an agent choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by explicitly stating that the access token itself is never exposed, only a prefix and expiry metadata, which is valuable security-relevant information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by a precise security note and a structured return summary. Every sentence contributes information without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, a provided output schema, and annotations that fully cover the safety profile, the description is complete. It tells the agent what state is reported, confirms sensitive token data is not returned, and lists the JSON fields, so no essential context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description still adds value by clarifying what the reported state consists of, including configured env vars, token expiry, scope, and whether a refresh token exists, even though no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb, 'Report', with a clear resource, 'OAuth login state', and enumerates the exact fields returned. This makes it unambiguous and naturally distinguishes it from OAuth action siblings like nexus_oauth_login, nexus_oauth_refresh, and nexus_oauth_logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use it — to inspect the current OAuth login state rather than to log in, log out, exchange, or refresh. However, it never explicitly states conditions, exclusions, or names alternatives, leaving the comparison to be inferred from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the annotations: the operation requires moderator permissions, uses v2 GraphQL, and returns either {success} or an error string. It does not deeply describe side effects, but the mutation scope is clear from the name and annotations already indicate it is non-read-only and idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, purpose first, no filler, and the return behavior is clearly stated. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with complete schema descriptions, helpful annotations, and a stated return shape, the description is fully sufficient. The agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage for both required parameters, including a helpful cross-reference for badge_id. The description itself does not add additional parameter semantics, so the schema carries the weight and baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb-resource pair: 'Remove a badge from a collection'. It also adds relevant context (moderator permissions required, v2 GraphQL) and is easily distinguished from the sibling tool nexus_add_badge_to_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite ('moderator permissions required') and the intended use case is obvious from the action. However, it does not explicitly name the alternative add tool or describe when not to use this tool, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds useful context beyond annotations: the rate-limit pool behavior and the concrete return shape ('JSON {removeFavouriteGame: {success}} or an error string'). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. It uses three short, information-dense sentences covering what, rate-limit behavior, and return format. No wasted words or redundant restatements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, non-destructive action with full schema coverage and an output schema, the description is complete. It covers the action, API pool, and response shape, leaving no critical ambiguity for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the game_id property already includes 'Game ID to remove from favourites.' The description does not add further parameter details, but it doesn't need to since the schema fully documents the single parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Remove a game from your favourites via v2 GraphQL.' This unambiguously distinguishes it from sibling tools like nexus_add_favourite_game and nexus_get_favourite_games. The title 'Unfavourite a game (v2)' reinforces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical usage context by stating it consumes the v2 GraphQL pool rather than the v1 REST rate-limit quota, which helps an agent decide between API versions. It does not explicitly name a sibling tool as an alternative, but the purpose statement implicitly routes away from add/get favourites tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as non-read-only and idempotent. The description adds valuable behavioral context beyond annotations: it consumes the v2 GraphQL pool rather than the v1 REST quota, and it discloses the exact return shape (JSON {removeKudos: {success}} or an error string). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose, followed by a useful quota note and return format. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description is complete: it states the action, the target user, the transport/quota behavior, and the return shape. An agent has enough information to select and invoke this tool correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, user_id, and the schema already documents its type, minimum, and meaning at 100% coverage. The description adds no additional parameter-level detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Remove') and resource ('previously given kudos from a user') and specifies the transport (v2 GraphQL). It clearly distinguishes this from the sibling nexus_give_kudos by describing the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to call this tool: to remove kudos already given to a user. It also provides operational guidance about consuming the v2 GraphQL pool rather than the v1 REST quota, which helps an agent choose an appropriate path, though it does not explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond those annotations: it is backed by the v2 GraphQL API and does not consume v1 REST quota, and it explains that results are returned 'best matches first' with a warning to take domainName from the intended node. This gives agents actionable insight into how results should be handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured and front-loaded: the core purpose appears in the first sentence, followed by clear usage guidance and a compact return shape block. Every sentence contributes information about purpose, usage, or output, with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, read-only tool with rich annotations and an output schema, the description covers everything needed to select and invoke it correctly: what it does, when to call it, what it returns, and how to interpret the results. There are no critical gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single parameter game_name, including examples like 'Skyrim Special Edition' and 'fallout 4.' The description reinforces the meaning by explaining the game_name is the display name and the output is the slug, but it does not add significant meaning beyond the schema's existing description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Resolve a game display name to its domain_name slug,' which immediately states the tool's exact purpose. It also clarifies that this is a convenience wrapper and that most other tools require the lowercase slug, making its role distinct from siblings like nexus_search_games or nexus_get_games.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Call this first when you only know the game's name, then pass the returned domainName value to the other tools.' This establishes clear usage context and sequencing. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls just short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=false, so the description's 'ACTION, not a read' reinforces that but adds meaningful context about initiating a verification session and returning a URL to open. This is sufficient for an agent to understand the tool's side-effectful nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose, and every line adds value: what it does, that it is an action, and what it returns. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter action tool with an output schema, the description is complete. It conveys the operation, side-effect nature, and the return shape with a clear instruction to open the returned URL.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema already documents this fully. The description appropriately indicates the operation targets 'the current user,' which is useful context even though no explicit parameter is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the specific action: 'Start the age verification flow for the current user (v2 GraphQL).' It also emphasizes this is an ACTION that initiates a session, distinguishing it from read-only verification info tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some guidance by explicitly saying 'This is an ACTION, not a read,' which helps rule out read-only verification lookup tools like nexus_get_age_verification_info. However, it does not differentiate from the closely related sibling nexus_start_age_verification_appeal_flow or state when one should be preferred over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral detail by explaining the idempotent behavior via HTTP status codes (200 already tracking, 201 newly tracked). This goes beyond the annotations, which only declare readOnlyHint=false, destructiveHint=false, idempotentHint=true. It doesn't contradict annotations and adds context about the operation's effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the action and purpose, the second outlines the return format. There is no wasted language, and the purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two well-documented parameters and an output schema, the description covers the essential behavior and return values. It is complete given the annotations and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides thorough descriptions for both parameters (mod_id and domain_name), including an example format and a warning about not using display names. Since schema coverage is 100%, the tool description doesn't need to add extra parameter detail. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'track' and resource 'mod' for the authenticated account, and clarifies the action is for getting update notifications. This clearly distinguishes it from sibling tools like nexus_get_tracked_mods (list tracking) and nexus_untrack_mod (stop tracking).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (starting notification tracking) but does not explicitly contrast with alternatives like nexus_untrack_mod or nexus_get_tracked_mods. The intent is clear, though a brief mention of related tools would strengthen it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover idempotency and non-destructiveness. The description adds the meaningful permission requirement and the return contract ('JSON {success} or an error string'), which go beyond the structured annotations. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the action is stated first, followed by the key permission caveat and the return format. Every sentence earns its place without redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter mutation tool with annotations and an output schema, this description covers the essential context: what the tool does, the permission boundary, and the response shape. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes `user_id` well ('User ID. Omit for the current user.'), so the baseline is strong. The description adds valuable parameter-related context by clarifying that targeting another user requires moderator permissions, which helps the agent decide whether and how to populate `user_id`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action and target: 'Unblock a user's mods from earning Donation Points via v2 GraphQL.' This clearly distinguishes it from the sibling `nexus_block_mods_from_earning_dp` while also stating the exact resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a useful prerequisite ('Requires moderator permissions when targeting another user') and implies the tool is for reversing a block, but it never explicitly states when to prefer this tool over the sibling block tool or when not to use it. The usage context is mostly implied by the name and sibling list rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses that this operation has no public side effect and that reads can lag several seconds after success. It also states the return shape. This is meaningful behavioral context worth credit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the primary purpose, then gives the key behavior caveat, and ends with the return format. Each sentence earns its place; there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation tool, this definition is complete: it explains what the tool does, its side-effect profile, a critical eventual-consistency caveat, and the expected output. The output schema exists, so no further return-value documentation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents tag_id as an integer with minimum 1 and description 'Tag ID to unblock.' The tool description adds no extra parameter-level meaning, but since schema coverage is 100%, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Unblock') and resource ('previously blocked tag') and mentions the v2 GraphQL mechanism. This clearly distinguishes it from sibling tools like nexus_block_tag and nexus_get_blocked_tags without needing to inspect their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is a personal-preference operation with no public side effect, and it warns that list reads via nexus_get_blocked_tags can lag, so re-reading immediately is not reliable. It doesn't explicitly say 'do not use this for public tag state,' but the personal-preference scoping implies the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds meaningful behavioral context beyond those: it specifies the rate-limit pool used ('Consumes the v2 GraphQL pool, NOT the v1 REST rate-limit quota') and explicitly describes the return payload ('JSON {untrackUser: {success}} or an error string'). No contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, dense sentences, each serving a distinct purpose: the action statement, the rate-limit caveat, and the return format. No filler or redundancy; the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with annotations, a 100% covered schema, an output schema signal, and a return format stated in the description, nothing essential is missing. The rate-limit behavior and output shape are both covered, making the definition complete for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single parameter user_id is already well documented in the schema with its type, minimum, and purpose ('Nexus Mods member ID to stop tracking'). The description adds no additional parameter semantics, which is acceptable given the schema's completeness; the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Stop tracking a user via v2 GraphQL' — a specific verb and resource that immediately distinguishes it from sibling tools like nexus_track_user (opposite action) and nexus_untrack_mod (different resource). The title 'Untrack a user (v2)' reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context note that this tool consumes the v2 GraphQL pool rather than the v1 REST rate-limit quota, which is useful operational guidance. However, it does not explicitly state when to use this tool versus alternatives such as nexus_track_user or nexus_ignore_user, nor does it provide any exclusion criteria or alternative tool routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the crucial partial-update behavior ('Only the provided fields are changed; omitted fields stay as-is') and the return format ('JSON {success} or an error string'). Annotations already declare non-destructive and idempotent, so the description builds on that without contradiction. It does not note authentication or error details, but the partial-update and return semantics add real value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no fluff: purpose, behavior, and return. It is front-loaded with the core action and provides the key behavioral nuance immediately. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 26 optional parameters, the schema thoroughly documents each one. The description covers the overall behavior (partial update), points to the read tool for pre-fetching, and specifies the return format. No critical operational detail is missing for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter has a descriptive comment in the schema. The description adds a generic semantic that applies to all parameters: only provided fields change, which is helpful but not per-parameter. Given the high schema coverage, the baseline of 3 is appropriate; the description does not enumerate or elaborate on individual parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Update the current user's site preferences via v2 GraphQL.' The verb 'Update' plus the resource 'site preferences' clearly distinguishes it from siblings like nexus_update_about_me and nexus_update_country, and from the read-only nexus_get_preferences. The partial-update note adds further specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions the read counterpart: 'Read current values with nexus_get_preferences,' which guides the agent to fetch existing preferences first. While it doesn't explicitly exclude other update tools, the resource name 'preferences' makes the appropriate context clear. This is sufficient guidance but lacks an explicit 'when not to use' statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a mutating, non-read-only operation. The description adds meaningful behavioral detail beyond that: it creates both a collection and its first draft revision, and it specifies the exact return shape ({success, collectionId, revisionId}) or an error string. This is valuable context for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: purpose in the first sentence, invocation guidance in the second, and return behavior in a short block. Every sentence earns its place with no filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters and a high-complexity create operation, the description provides a solid orientation: what is created, two ways to provide the payload, and the expected return. The schema and output schema cover field-level specifics; the main missing piece is explicit guidance about when not to use this tool relative to edit/update siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds significant semantic value by explaining the relationship between the individual params and collection_data_json, and by providing the expected JSON shape ({adultContent, collectionManifest: {info: {...}, mods: [...]}, collectionSchemaId}), which is not fully captured in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Create a new collection and its first draft revision (v2 GraphQL).' This clearly differentiates it from sibling tools like nexus_edit_collection and nexus_create_or_update_revision, and clarifies it creates both a collection and an initial draft revision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this to create a new collection, not to edit or update an existing one. It also explains the two valid invocation strategies (individual params vs. collection_data_json), though it does not explicitly name alternatives or exclusions like 'use nexus_edit_collection for existing collections.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by disclosing that this operation consumes the v2 GraphQL pool rather than the v1 REST rate-limit quota, and it clarifies the return shape, including an error string option. The annotations already indicate a non-read-only, non-idempotent write operation, and the description's behavior aligns with that. It stops short of detailing auth requirements or potential side effects, but it adds meaningful operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: the primary action is front-loaded, the nested-reply condition is stated immediately, and the additional rate-limit and ID-location guidance is separated into a concise paragraph. The Returns section is clearly formatted and every sentence contributes useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter write operation, the description is largely complete: it covers required parameters, the optional reply_to_id, thread ID discovery, rate-limit behavior, and the response shape. It does not explicitly mention authentication prerequisites or post-creation effects, but those are somewhat covered by annotations and the surrounding API context. Overall, an agent has enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that thread IDs are found on mod pages and that forum threads and mod posts have distinct IDs. It also reinforces the reply_to_id behavior ('nested reply when reply_to_id is given'), which is already in the schema but is made more actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific action and resource: 'Post a comment in a thread via v2 GraphQL.' It immediately clarifies the top-level vs. nested reply distinction, which differentiates this from related comment tools like nexus_edit_comment or nexus_discard_comment. The scope is unambiguous and the tool's identity is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: top-level by default, or a nested reply when reply_to_id is provided. It also provides operational guidance on where to find thread IDs and warns that forum threads and mod posts have distinct thread IDs. It does not explicitly name alternative tools or state when not to use it, but the guidance is strong enough for an agent to select it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations, such as streaming to disk, computing MD5 and SHA-256 checksums, and returning a specific JSON structure or an error string. It also mentions the safety cap (max_bytes) and the need for key/expires for non-premium accounts, which are not in the annotations. It does not mention file overwrite behavior, but the annotations (destructiveHint=false) suggest no destructive intent, so this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main action, then a reference to the related tool, account-specific guidance, and a returns section. Every sentence carries useful information, and it is front-loaded with the primary purpose. The 'Returns:' block is neatly formatted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential context: the operation, account requirements, output format, and safety cap. It does not explicitly mention that the download could be large or that it might overwrite existing files, but given the schema covers destination and max_bytes, and the output format is documented, this is largely complete. A slightly more detailed error handling note would push it to 5, but 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter descriptions in the schema are already detailed (e.g., key/expires requirements, max_bytes safety cap, domain_name as lowercase slug). The description adds no new parameter semantics beyond what the schema provides; it only repeats the key/expires requirement and mentions the MD5 verification tip, which is a usage hint rather than parameter meaning. Thus, baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: resolve a mod file's CDN link and stream it to a local file. It explicitly distinguishes itself from nexus_get_download_link by saying 'Downloads the actual file behind nexus_get_download_link', and the title 'Download a mod file to disk' reinforces the purpose. No ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear when-to-use guidance by referencing the sibling tool nexus_get_download_link, implying use this tool when you need the file streamed to disk rather than just a link. It also gives conditional usage based on account type: premium can omit key/expires, non-premium must pass them from a .nxm link. This is explicit and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior; the description adds useful behavioral context: the rate-limit distinction, the mutual-exclusion requirement, and the caveat that per-game lists may be sparse. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and mode, and each sentence adds rate-limit, selection, or data-sparsity context. The return-shape line is slightly redundant given an output schema exists, but it is concise and does not hurt scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool, the description covers parameter selection, rate-limit behavior, data sparsity, and return shape. An agent has enough to invoke it correctly without consulting additional sources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a helpful description and example. The description adds the crucial 'exactly one of domain_name or is_global' constraint, which is not enforced or expressed in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get mod categories (per-game or global) via v2 GraphQL.' It also clarifies the category scale and style, which separates it from related resources like single-category or tag-category tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: provide exactly one of domain_name or is_global, and notes that the v2 GraphQL API does not consume the v1 REST quota. It does not explicitly name alternatives or when-not-to-use conditions, so it stops 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and idempotent behavior, so the description does not need to restate that. It adds useful context beyond annotations: the v2 GraphQL backing, the quota behavior, and the exact return shape (totalResolved, _returned, mods with the same shape as nexus_search_mods nodes). This is strong but not maximal; it does not mention any v2-specific limits or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized into purpose, quota context, and return shape, with the most important information front-loaded. It is compact, though the second sentence slightly restates the v2 GraphQL point already introduced in the first sentence, preventing a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a batch read tool, the description supplies all key non-schema context: when to use it, what quota it preserves, how it relates to nexus_get_mod, and what the response looks like. Combined with fully documented parameters and read-only/idempotent annotations, an agent has enough information to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a clear description with format, example, defaults, and bounds. The tool description adds no additional parameter-level semantics beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence uses a specific verb ('Fetch'), names the resource ('many mods'), and sets clear scope ('across games', 'single v2 GraphQL query'). It also explicitly positions itself as the 'Batch equivalent of nexus_get_mod', which distinguishes it from that sibling without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use it: 'ideal for resolving many mod IDs at once'. It names the single-item alternative, nexus_get_mod, and adds a concrete selection factor by noting it does NOT consume the v1 REST rate-limit quota. This gives an agent enough context to choose between batch and single-fetch tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), it discloses a non-obvious behavioral trait: data is hidden under plain API-key auth and the tool requires an OAuth exchange. It also reports that the tool surfaces the error otherwise, plus the return shape, giving the agent useful runtime expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and includes an auth note. The Return JSON block is useful but somewhat redundant with the existing output schema, so it is not perfectly lean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent, 7-optional-parameter tool with 100% schema coverage and an output schema, the description is complete. It covers scope, auth prerequisite, failure behavior, and the general result shape, so an agent can select and call it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes all seven optional parameters (pagination start, search string, bank_id, per_page, order_dir, account_id, order_column). The description adds no additional parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get Donation Points transactions for the current user (v2 GraphQL)', a specific verb, resource, and scope. This clearly separates it from the many other nexus_get_* tools, which target mods, games, collections, or user preferences.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the required auth flow: 'Requires OAuth login (nexus_oauth_login + nexus_oauth_exchange)' and warns that apikey-only auth hides the data and surfaces an error. It does not name alternative tools or state when not to use it, but the current-user scope and auth prerequisite give clear selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive, idempotent operation. The description adds value by disclosing partial-update behavior, a possible moderator permission requirement, and the exact return shape. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: action and scope, permission caveat, partial-update rule, and return format. Every sentence earns its place, and the most important purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6-parameter schema, output schema presence, and useful annotations, the description covers the permission caveat, partial-update behavior, and return format. It could be slightly stronger by naming sibling create/discard tools or making the moderator requirement more definitive, but nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each parameter is already defined. The description goes beyond the schema by explaining partial-update semantics: omitted fields are preserved, only supplied fields are changed. This is critical for safely invoking a 6-parameter update with only one required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Update an existing tag'. The word 'existing' clearly separates this from create/discard tag siblings, and 'via v2 GraphQL' adds implementation context. It is not a tautology and unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete invocation guidance: permissions may be required, and only provided fields are changed while omitted fields stay as-is. This tells an agent how to perform a partial update. It does not explicitly name when-not-to-use alternatives like nexus_create_tag or nexus_discard_tag, so it stops 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive, but the description adds substantial behavioral context: it is a soft-delete, the action consumes the v2 GraphQL pool rather than v1 REST quota, discarded comments are removed from public view, permission is limited to author/moderator, and restore auth limitations make the action one-way with API keys. This is far beyond what annotations alone convey and is directly useful for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence in the description earns its place: the operation definition, the rate-limit pool distinction, the permission scope, the restore-auth caveat, and the return shape. The content is organized into short labeled sections with no filler or redundancy. It is sufficiently detailed without being bloated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive operation, the description covers all essential context: what the operation does, who can perform it, what the side effects are, what the auth caveats are, and what the response looks like. The existence of sibling operations like nexus_hide_comment, nexus_lock_comment, and nexus_restore_comment emphasizes the need for this context, and the description handles it well. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents comment_id with a clear description and type constraint, and schema coverage is 100%. The tool description does not add much parameter-specific meaning beyond restating that a comment is being discarded; however, the behavioral context around authorship and restore limitations indirectly informs how the parameter should be chosen. Baseline 3 is appropriate because the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Discard (soft-delete) a comment via v2 GraphQL.' It distinguishes itself from sibling operations like hide, lock, or restore by specifying the soft-delete nature, author/moderator restriction, and explicitly referencing nexus_restore_comment as the complementary operation. An agent can immediately tell what this tool does without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when it applies: discarding a comment removes it from public view, only the author or a moderator can perform it, and restoring requires OAuth Bearer auth so discard is effectively one-way with apikey-only auth. This implies when not to use it (e.g., when restore may be needed under apikey-only auth) but does not explicitly name alternative tools such as nexus_hide_comment or nexus_lock_comment for less destructive moderation actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly/destructive/idempotent hints. The description adds useful behavioral context beyond those annotations: ownership requirement, partial update semantics, and the exact JSON success shape or error string. It contradicts no annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with purpose and ownership, then states the partial-update rule, then the return shape. No sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param metadata edit, the description covers the prerequisite, mutation semantics, and return/error behavior. Combined with 100% schema coverage and annotations, an agent has enough to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes every parameter (100% coverage), so the baseline is 3. The description adds meaningful semantics by clarifying that omitted optional fields are unchanged, which is essential for correctly using the seven optional parameters. It leaves the null-clearing behavior slightly implicit, so not a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Edit'), a clear resource ('collection's metadata'), and a concrete prerequisite ('must own the collection'). This distinguishes it from collection creation, deletion, listing, and revision tools in the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: editing metadata, requiring ownership, and the partial-update model ('Only the provided fields are changed; omitted fields stay as-is'). It does not explicitly name alternatives or exclusion cases, but the usage is not merely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that this uses the v2 GraphQL rate-limit pool, requires authorship, and returns either a structured JSON object or an error string. These details meaningfully inform an agent about auth expectations, quota behavior, and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the primary purpose, and every sentence adds distinct value: transport, auth condition, and return shape. The return block is clearly formatted and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation with full schema coverage and an output schema, the description covers purpose, auth, rate-limit pool, and return shape. There are no significant gaps that would prevent an agent from invoking this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, and both parameters already have descriptive schema entries explaining that body is plain text and comment_id must be one's own comment. The description reinforces 'own comment' but adds little parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Edit the body of your own comment via v2 GraphQL.' It clearly states scope (your own comment) and transport (v2 GraphQL), and the action is distinct from sibling comment tools like create, discard, or restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for use: only the comment's author can edit it and it consumes the v2 GraphQL pool rather than v1 REST quota. It does not explicitly name alternative tools or say when not to use this tool, but the preconditions and scope are clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that the call is read-only, idempotent, non-destructive, and open-world. The description adds behavioral context by specifying that it returns a JSON array and enumerating the exact response fields, including the status enum. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact lines plus a structured return contract. Every sentence contributes information, and the return format is cleanly separated. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only endpoint with strong annotations and a documented return shape, the description is complete. It tells the agent what the tool returns, the scope ('authenticated account'), and the possible status values. No additional operational details are necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema needs no additional explanation and the description has no parameter semantics to provide. The baseline of 4 for a parameter-less tool applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a specific resource ('the authenticated account's endorsement history'), making the tool's purpose immediately clear. It also naturally distinguishes itself from sibling tools like nexus_get_mod_endorsers (which lists endorsers for a mod) and nexus_endorse_mod (which creates or changes an endorsement).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames this as the tool for retrieving the caller's own endorsement history, which provides strong contextual guidance. However, it does not explicitly name alternatives or state when not to use this tool, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds non-obvious behavioral facts not present in annotations: the v2 GraphQL backend does not consume the v1 REST rate-limit quota, and the response omits domainName/modID, requiring separate resolution before download tools. These are high-value caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: core operation first, then use case, then key caveats, then return shape. Markers like 'Ideal when', 'NOTE', and 'Returns' make it easy to scan, and every segment earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple read-only nature, 100% schema coverage, and existing output schema, the description provides all needed selection and invocation context: when to use it, rate-limit behavior, a critical data gap, and the required follow-up before downloads. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so paramaters are already well documented with descriptions, bounds, and defaults. The description adds useful context about UID provenance and the lack of domain/modID, but does not add per-parameter semantics beyond schema. Basline 3 fits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description names the specific operation ('Get mod file lists by mod UID(s)'), indicates the API channel, and explicitly distinguishes from domain/modId-based lookups by saying no domain/modID pair is needed. This makes it clearly separable from sibling tools like nexus_get_mod_files and nexus_get_files_v2.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Ideal when you only have the uid' gives clear selection context with concrete examples (.nxm link or mod pipeline). It also instructs the agent to resolve the owning game/mod before calling download tools. However, it does not explicitly name an alternative tool or state when NOT to use it, so it falls just 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds useful behavioral context by specifying the API version, the rate-limit pool consumed, and the exact return shape. This goes beyond what annotations provide without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then adds a concise rate-limit note, and finally a compact return-format listing. Every line earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with rich annotations and an output schema, the description is complete. It identifies the resource, API version, rate-limit behavior, and returned fields. There is no missing information an agent would need to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially fully covered and there are no parameter semantics to explain. The baseline for zero-parameter tools is 4, and the description appropriately avoids inventing parameter details. The return shape note is extra useful context, though not parameter-related.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get the current user's ignored (muted) users via v2 GraphQL.' This immediately identifies both the action and the target data, and differentiates it from mutation siblings like nexus_ignore_user and nexus_unignore_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly contextualizes when to use the tool: to retrieve the current user's ignored/muted users. It also adds a meaningful usage note about consuming the v2 GraphQL pool rather than the v1 REST rate-limit quota, which helps an agent select it for rate-limit-aware workflows. It does not explicitly mention alternatives or exclusions, but the purpose is self-evident enough for this zero-parameter read tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by summarizing the response contents (adult, tabs, sort/search, download location, reminders, notification booleans) and noting the v2 GraphQL interface.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and uses a compact returns list. Every sentence adds useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless getter with rich annotations and an output schema, the description is complete. It identifies the current-user scope, the response areas, and the corresponding update tool, leaving no critical gap for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100%, so there are no parameter semantics to document. The baseline of 4 applies because no parameter information is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 the current user's site preferences (v2 GraphQL).' It clearly identifies the current user as the scope and distinguishes the operation from the sibling nexus_update_preferences by explicitly directing edits there.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for reading preferences and names nexus_update_preferences for editing, providing useful routing. It does not explicitly list when-not-to-use scenarios or compare with other getter tools, but the context is clear enough for a zero-parameter getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral information beyond that by specifying the return shape: 'JSON string URL or an error string.' This gives the agent expectation about both success and failure outputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded sentences with no filler. It states the purpose first and the return type second, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter, clear return format, and strong annotations covering read-only/idempotent behavior, the description is complete for correct invocation. No important behavioral context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents message_id as 'Private message ID' with a minimum of 1. The description adds extra semantic value by clarifying that the ID refers to one of the authenticated user's own private messages, which is not stated in the parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 the web URL for one of your private messages (v2 GraphQL).' This clearly distinguishes it from sibling URL-related tools like nexus_get_download_link or nexus_get_speedtest_urls by naming private messages as the target resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool is for private messages owned by the caller ('one of your private messages'). It does not explicitly name alternatives or when-not-to-use conditions, but the private-message scope itself provides adequate differentiation from the other get-URL tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context that this runs against the v2 GraphQL pool and returns a structured array of mirror metadata, complementing rather than contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loads the core purpose, gives a practical usage tip, and ends with a precise return format. Every sentence contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with a stated output shape and supporting annotations, this description fully covers what an agent needs to select and invoke it. The use case, return type, and field names are all specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema leaves nothing undocumented. The description correctly focuses on what the tool returns rather than parameter details, matching the baseline for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 CDN speedtest URLs to diagnose download issues via v2 GraphQL.' It clearly distinguishes this tool from siblings like download or search tools by focusing on speedtesting mirrors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance: 'Handy when downloads feel slow: test latency/throughput against each mirror and compare.' It does not explicitly name alternatives or exclusions, but the use case is clear and the tool is unique among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the GraphQL v2 transport and the exact returned JSON structure including nested tag fields, which enriches the agent's understanding of what it will get back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, stating the purpose in one sentence and then giving a precise return shape. Every element serves a distinct purpose, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter signature, a simple list-all operation, strong annotations, and an available output schema, the description is fully adequate. The explicit return format covers what an agent needs to know before invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so parameter documentation is not needed. The baseline for 0-parameter tools is 4, and the description correctly avoids inventing parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List all tag categories with their tags,' which clearly identifies the operation and its scope. The addition of '(v2 GraphQL)' and the explicit return shape distinguish it from sibling tools like nexus_get_tags or nexus_get_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: when you need all tag categories with their embedded tags, this is the tool to use. It does not explicitly name alternatives or exclusions, but the operation is specific enough that usage is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and idempotent annotations, the description discloses exact-match behavior, the clean failure mode, and the precise return shape including the null case. This tells an agent exactly what to expect when calling the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: the core purpose appears in the first line, the distinguishing contrast follows, and the return contract is placed at the end. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only lookup with a rich annotation set and an output schema, this description is complete. It covers purpose, exact-match behavior, failure semantics, return value shape, and a concrete use case. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the username parameter as exact and case-sensitive with an example. The description adds the use-case context of converting username to memberId, but most parameter semantics are already covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: getting a user profile by exact username, and explicitly distinguishes itself from the fuzzy search_users sibling. It is immediately clear what this tool does and how it differs from similar lookup tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly contrasts itself with nexus_search_users and gives a concrete use case: converting a username to a memberId for user mutation tools. It does not enumerate other alternatives, but the exact vs. fuzzy distinction provides enough guidance for the main alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and idempotent behavior. The description adds valuable context beyond annotations by disclosing that it uses v2 GraphQL without consuming v1 REST quota and by specifying the exact return shape. This is useful behavioral detail not otherwise available.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, a short contextual note about API versioning and rate limits, and a compact return shape. Every sentence serves a distinct purpose without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only listing tool, the description fully covers purpose, usage, backend behavior, rate-limit implications, and the return format. It even names the related follow-up tool, making it complete for agent decision-making and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single account_id parameter with type, minimum, and description, so the description adds no additional parameter-level semantics. The description does relate the output to userId, which is a minor extra, but the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('months a user has a monthly activity report for'), and explicitly differentiates itself from the detailed report tool by noting the follow-up for download/upload numbers. This makes the tool's purpose unmistakable and clearly distinct from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: use this to list available months, then follow up with nexus_get_user_monthly_report for specific monthly numbers. It also notes the v2 GraphQL backend and its rate-limit behavior, which helps the agent decide when this tool is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond annotations: it clarifies the v2 API backing, that it bypasses v1 quota, and enumerates the returned fields. This gives the agent confidence about the call being non-mutating and quota-friendly without needing to open the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-ordered: purpose first, then the key usage constraint, then the API/quota note, then a concise list of returned fields. Every sentence carries information and none are wasted. It is front-loaded with the most important information for tool selection and invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent user-profile getter, the description covers the scope, lookup keys, exclusivity requirement, API family, and quota behavior. The output schema exists, so the listed return fields are a useful summary rather than a necessity. Nothing critical for calling this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a descriptive label and example. The description adds the key semantic constraint that exactly one of member_id or username must be provided, which is not expressed as required in the schema. It also frames both parameters as lookup keys for the same public resource. This goes beyond the schema's individual field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb-resource pairing: 'Get a public Nexus Mods user profile' by member ID or exact username. This immediately distinguishes it from search tools and the sibling nexus_get_user_by_name, which is username-specific. The v2 API mention and field list further pin down its identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit calling guidance: 'Provide exactly one of member_id or username.' It also adds the v2 GraphQL API distinction and the note that it does not consume v1 REST rate-limit quota, which helps an agent understand when this tool is preferable. It stops short of explicitly naming alternatives or stating when not to use this tool, so it falls just below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: the tool is backed by v2 GraphQL, avoids v1 REST quota, returns a specific JSON shape, and returns null for nonexistent types. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-line purpose, a short note on backend/rate-limit behavior, and a clear return summary. Every sentence adds distinct value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single well-documented parameter, an output schema, and strong annotations, the description covers all key decision factors: what it introspects, why it is useful, the API backend, rate-limit implications, and the return/null behavior. Nothing important is missing for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, type_name, and the schema description covers it fully with examples like 'Mod', 'ModsFilter', and 'Collection.' The description adds no additional parameter detail, but with 100% schema coverage the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Introspect any type in the Nexus v2 GraphQL schema,' naming a specific verb, resource, and scope. It also explicitly frames its role as a discovery step for nexus_graphql_query, which differentiates it clearly from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is 'useful for discovering filters, sorts, and fields before composing a query with nexus_graphql_query,' giving an explicit use case and pointing to the companion tool. It also adds the operational advantage that it does not consume the v1 REST rate-limit quota, helping the agent decide when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses meaningful side effects: tokens are saved to a token file, identity is validated with the resulting Bearer token, tokens auto-refresh, and 4xx refresh responses are treated as revocation. This goes well beyond the annotations and gives the agent a realistic model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear purpose statement, a compact description of mechanics, a note on refresh behavior, and a return summary. Every sentence contributes useful information without redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the full invocation context: what it exchanges, how it authenticates, where tokens are stored, how refresh failures behave, and what it returns. Combined with full schema coverage and the output schema, nothing essential is missing for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters fully: code and state are described with origin and verification behavior. The tool description adds process context around PKCE and client_secret but does not materially enhance parameter-level understanding, so the high-coverage baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'exchange the authorization code for tokens,' clearly identifying this as the OAuth token exchange step. It also clarifies the tool completes the OAuth2 flow and validates identity, which distinguishes it from related OAuth siblings like login, refresh, status, and logout.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly signals this is the post-redirect step by mentioning the authorization code and PKCE exchange, and the schema explicitly references the 'OAuth redirect after nexus_oauth_login.' It does not explicitly name alternative tools or state when not to use it, but the intended usage context is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: it discloses the use of PKCE S256 and random state, explains that bearer tokens take precedence over NEXUS_API_KEY, and describes the returned JSON structure. This gives the agent important security and workflow context that annotations alone do not convey. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it front-loads the core purpose, then gives required security context, the follow-up step, and the return shape. Every sentence earns its place, and the 'Returns' block is clear and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter optional tool with a documented output schema, the description is complete. It covers the full OAuth flow from starting the flow, returning a URL, capturing the code, exchanging it, and understanding the resulting token precedence. An agent has enough context to invoke the tool and handle its output correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters well. The description does not add meaningful new meaning to the parameters themselves, and it does not need to because the schema covers scope defaults and redirect_uri override rules. This is the expected baseline for fully self-documenting schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Start the OAuth2 authorization-code flow' and 'returns the URL to open in a browser.' It also clearly distinguishes this from the related OAuth siblings by explaining that the returned code must be passed to nexus_oauth_exchange, making the tool's role in the flow unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: to initiate OAuth login and obtain a browser URL. It explicitly points to the next step in the flow (nexus_oauth_exchange) and explains that bearer tokens unlock user-context mutations. However, it does not explicitly state when not to use it, such as checking nexus_oauth_status first or using nexus_oauth_refresh for existing tokens.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by disclosing that the local token file is removed, that the system falls back to NEXUS_API_KEY, and that full revocation requires separately removing the authorized application at an external URL. The idempotentHint and destructiveHint annotations are not contradicted; this is a safe, idempotent logout.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences front-load the primary effect (delete tokens, fallback), then clarify the local side effect and the external revocation caveat. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool with an output schema and annotations already covering idempotency, the description is fully complete. It covers side effects, fallback authentication, external revocation, and return value, so an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema has 100% coverage (an empty properties object), so the baseline is 4. The description correctly implies no arguments are needed and adds no parameter details, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes stored OAuth tokens and falls back to NEXUS_API_KEY authentication. This is a specific verb+resource and distinguishes it from sibling OAuth tools like nexus_oauth_login, nexus_oauth_refresh, and nexus_oauth_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this is the logout action, as opposed to login, refresh, or status checks among the OAuth siblings. However, it does not explicitly list when-not-to-use conditions or directly name alternatives, so it falls short of the full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses the v2 GraphQL mechanism and the return contract: JSON {comments:[{id}]} in the new order or an error string. Annotations already indicate mutation and idempotence, so the description adds useful contract details without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short focused statements: purpose, required input, return value. 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter, a complete schema description, output schema present, and annotation coverage for idempotence/destructiveness, the description provides all necessary context. The only minor omission is explicit exclusion of non-pinned comments, but 'pinned comment IDs' covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter comment_ids is fully described in the schema as 'Comma-separated pinned comment IDs in the desired order.' The description adds the crucial requirement to pass ALL pinned IDs, emphasizing the non-incremental, full-set semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Reorder') and resource ('pinned comments in a thread'), clearly identifying the operation. It is distinct from sibling tools like nexus_pin_comment or nexus_reorder_item because it targets the ordering of already-pinned comments, not pinning or collection item reordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Pass ALL pinned comment IDs of the thread in the desired order' gives a clear, mandatory usage pattern and implies this is a whole-set replacement rather than a partial reorder. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/destructive annotations, the description discloses a meaningful behavioral trait: the v2 GraphQL API does NOT consume the v1 REST rate-limit quota. It also documents the exact return shape and positions this tool as a search complement to the full catalog, adding substantial context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then a single high-value behavioral distinction, then the return contract. Every sentence earns its place and there is no redundant restating of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema documents all parameters, annotations cover the safety profile, and the description supplies the return schema plus a rate-limit relevant detail. For a read-only search tool with all-optional parameters, nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented in the input schema. The description's 'by name' phrase loosely maps to the term parameter, but it adds no meaning beyond what the schema already provides for sort, count, offset, or direction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a specific verb and resource: 'Search Nexus Mods games by name, sorted and paginated'. It explicitly distinguishes itself from the sibling nexus_get_games by calling it a complement and labeling that sibling as the full cached catalog, so an agent can tell them apart immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the relevant alternative, nexus_get_games, and implies the usage boundary by contrasting a name-search with the full cached catalog. It does not explicitly state 'use this when you need name search' but the context is clear enough to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing the server-side flakiness pattern, including the exact error shape and the retry recommendation. It also documents the deliberately removed adultContent filter and explains the return shape and pagination behavior. This is rich, honest behavioral context that an agent needs to use the tool reliably.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: purpose first, followed by critical caveat, then return format and pagination. Every sentence carries operational value, especially the flakiness note and the offset pagination rule. It is longer than one sentence, but the length is justified by the complexity and failure mode.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 optional parameters, a full input schema, an output schema, and read-only/idempotent annotations, the only major missing context would be practical operational guidance. The description covers the key gaps: retry behavior, removed filter, union return types, and how to paginate. Nothing needed for correct invocation is overlooked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since the input schema already documents all 10 parameters at 100% coverage, the baseline is 3. The description adds genuine extra value by explaining pagination mechanics ('Paginate with offset += _returned') and warning about a filter that was deliberately excluded. It does not perfectly annotate every parameter, but it supplements the schema where practical behavior matters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search site-wide media (images, supporter images, videos) via v2 GraphQL.' This clearly distinguishes it from sibling search tools like nexus_search_mods, nexus_search_users, and nexus_search_games. The scope is unambiguous and immediately actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear context for media searching and labels the endpoint as site-wide, which implies when it should be used. However, it never explicitly names alternatives or states when not to use this tool. There is no exclusion guidance, but the resource focus is concrete enough to orient an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description reveals useful behavioral detail: the call is backed by v2 GraphQL and does not consume the v1 REST rate-limit quota. It also documents the returned JSON shape, pagination semantics ('offset += _returned'), and the notable exclusion of full BBCode descriptions, which is actionable context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then adds a compact technical note, a clear return-shape block, and a routing note for full details. Every sentence earns its place; there is no padding or repetition of schema contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, all-optional search tool, the description is complete: it explains the API backend and rate-limit behavior, gives the return shape and pagination strategy, and points to the correct sibling for missing data. The rich input schema and annotations cover the remaining operational details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter thoroughly, including defaults, enums, constraints, and special notes like the server page-size cap. The description adds only high-level context ('free text + filters') without duplicating parameter-specific semantics, which is appropriate for the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Search Nexus Mods with free text + filters, sorted and paginated.' It also clarifies this is the only way to search mods by name because the v1 REST API has no free-text search, distinguishing it from other search-family siblings like nexus_search_collections or nexus_search_users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool: it is the only way to search by name since the v1 REST API lacks free-text search. It also directs users to nexus_get_mod_v2 when full mod descriptions are needed. However, it does not spell out exclusions for related search tools such as collections, users, or comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a non-read-only, idempotent mutation; the description adds the critical OAuth-only constraint and the failure mode under apikey-only auth. It also discloses that the response is a JSON payload or an error string. This goes beyond what annotations alone reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: a purpose sentence, an auth warning, a use case, and a return line. There is no filler or redundant restatement of the schema. It is front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation, the description covers purpose, auth prerequisite, failure mode, and return behavior. The output schema covers exact return fields, so nothing critical is missing. It is complete enough for an agent to decide and invoke safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents both parameters at 100% coverage, so the baseline is 3. The description adds the ownership requirement ('your own mod', 'mod authors'), which clarifies that mod_uid must belong to the authenticated user. The enabled boolean is also self-explanatory from the first sentence.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states the exact operation: enabling or disabling direct (no-ads) downloads for the user's own mod, and scopes it to the v2 GraphQL API. This is clearly distinct from the many get/download siblings and from user-preference mutations. The annotation title reinforces the toggle semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the precondition that OAuth login is required and that apikey-only auth will be rejected, which tells an agent when not to invoke it. It also identifies the intended audience (mod authors automating release pipelines). It doesn't name a sibling alternative, but no sibling appears to provide the same toggle, so the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/non-destructive annotations, the description discloses that the v2 API does not consume v1 REST rate-limit quota, surfaces a known server-side HTTP 500 issue, and notes possible extra permissions for some threads. These are exactly the behavioral details an agent needs to interpret errors and decide whether to proceed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than minimal, but every block carries non-redundant information: purpose, API/rate-limit context, invocation constraint, known issue, permission caveat, and return shape. The structure front-loads the purpose and separates the return format clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with an output schema, the description covers the only decision point (term vs thread_id), error behavior, rate-limit implications, and the response structure. An agent has enough information to invoke it correctly and interpret the result without opening the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter already has a meaningful description, so the baseline is 3. The description adds the critical mutual-exclusion rule between term and thread_id, which the schema cannot express, and maps each operating mode to its corresponding parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search Nexus Mods comments by text or list a thread's comments.' It clearly distinguishes the two operating modes and differentiates the tool from sibling comment tools like nexus_get_comment, nexus_create_comment, and nexus_get_comment_thread, which cover different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the critical invocation constraint: 'Provide exactly one of term or thread_id.' It does not explicitly name alternative sibling tools or say when not to use this tool, but the two-mode framing and parameter guidance give enough context for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the operation is personal-only, has no public side effect, is reversible, only affects blockable tags, and that preference mutations apply immediately while list reads may lag several seconds. This is rich, useful behavioral context that the annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the main action is front-loaded, followed by scope, reversibility, an important eventual-consistency note, and the return format. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter preference mutation, the description covers purpose, side effects, reversibility, constraints, eventual consistency, and return format. Combined with full schema coverage and output schema presence, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the sole parameter with type, minimum, and source guidance. The description adds the extra semantic constraint that only blockable tags can be blocked, which helps validate acceptable values beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Block a tag'), the resource ('for the current user'), and the effect ('hides matching content'). It clearly differentiates itself from related siblings by emphasizing it is a personal preference with no public side effect and explicitly names nexus_unblock_tag as the reverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is a personal preference mutation, reversible via nexus_unblock_tag, and only works on blockable tags. It does not explicitly enumerate alternatives beyond the unblock sibling, but the personal-scope framing adequately suggests when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: it is backed by v2 GraphQL, exempt from v1 rate-limit quota, static, cacheable, and returns a specific JSON shape. No contradiction exists between the description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose appears first, followed by operational guidance and return format. Each sentence contributes distinct value with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a zero-argument, read-only static catalog tool with an output schema and rich annotations, the description covers invocation, caching behavior, backend/rate-limit implications, and return structure. Nothing operationally important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there are no parameter semantics for the description to clarify beyond what the schema already shows. The baseline score of 4 applies because no parameter documentation burden exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List all badges a mod can earn', with concrete examples ('Top pick', 'Easy install'). This clearly distinguishes it from mutation siblings like nexus_add_badge_to_collection and other lookup tools such as nexus_get_tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear usage context by identifying the data as a static catalog and advising the agent to cache the result. It also notes the v2 GraphQL API does not consume v1 REST quota, which is useful for deciding when to call it. It does not explicitly name alternative tools or when not to use it, but this is a zero-argument read-only lookup with few competing siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnly/idempotent/non-destructive behavior. The description adds meaningful behavioral detail beyond that: it clarifies the underlying API version, the rate-limit advantage, the two-step uid resolution with caching, and the exact pagination/return shape. This gives an agent a solid mental model of what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Every subsequent sentence adds useful operational detail: API backing, rate-limit behavior, resolution strategy, and return/pagination format. There is no filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description sufficiently covers purpose, usage context, behavioral quirks, and pagination. An agent can confidently invoke this tool correctly without needing additional clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that mod_id is resolved to a uid first, which clarifies the relationship between the parameter and the underlying GraphQL API, and by explicitly instructing pagination via after_cursor. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List users who endorsed a mod via v2 GraphQL.' This clearly identifies the tool's function and distinguishes it from related siblings like nexus_get_endorsements or nexus_endorse_mod by focusing on listing endorsing users rather than endorsement state or action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when this tool is preferable by noting it uses the v2 GraphQL API and does NOT consume the v1 REST rate-limit quota. It also explains the two-step cached resolution. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses raw pass-through behavior, v2 API usage, the fact that v1 rate-limit quota is not consumed, and the clean failure mode for mutations. It also specifies the exact return format: raw 'data' JSON or 'Error: ...' with GraphQL error messages. This meaningfully exceeds what the annotations alone communicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized: purpose, endpoint/quota note, prerequisite, usage scope, and return format. Every sentence contributes a distinct fact; there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a raw GraphQL power-user tool, it covers prerequisites, allowed usage, failure behavior, and return format. It names the related nexus_graphql_introspect sibling and explains the relationship. The input schema covers all parameters, making the description complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both query and variables already having clear descriptions and concrete examples. The description adds contextual guidance about building valid queries but does not need to restate the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Run a raw query against the Nexus v2 GraphQL API (power-user escape hatch)'—a specific verb, resource, and positioning. It clearly distinguishes itself from the many v1 REST siblings and from nexus_graphql_introspect by framing itself as the raw query executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Introspect types with nexus_graphql_introspect first to build valid queries' and says to 'Use for read-only queries'. It also warns that most mutations require OAuth scopes the server lacks and 'will fail cleanly', giving a clear exclusion and expected failure mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the action is private, reversible, applies immediately, and that list reads can lag several seconds. It also states the return shape. These are meaningful behavioral traits that the annotations do not provide, making the description genuinely informative.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, privacy scope, reversibility, parameter requirement, read-lag warning, and return format are all covered in a few compact lines. The description is front-loaded with the core behavior and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with annotations and an output schema, the description is complete. It covers what the tool does, when it should be used, how parameters relate, behavior after invocation, reversibility, and the response format. There are no significant gaps an agent would need to fill by guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already documented. The description adds the important clarification that at least one of user_id or username must be provided, which is not obvious from the schema since both are nullable and no parameters are marked required. This adds real value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Ignore (mute) a user' and immediately clarifies the observable effect: 'hides their content in your feed.' It also distinguishes itself from the sibling tools by explicitly naming the reverse operation, nexus_unignore_user, so an agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is a personal, private preference with no public side effect, and it points to nexus_unignore_user as the reversible counterpart. It also warns about read lag when verifying via nexus_get_ignored_users. It stops short of explicitly saying 'use this only when...' or 'do not use when...', so it is strong but not perfectly explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the GraphQL pool versus v1 REST rate-limit distinction, the OAuth Bearer auth requirement, the visibility effect ('comment becomes publicly visible again'), and the exact return payload shape. This substantially enriches the behavioral context beyond the readOnlyHint, idempotentHint, and destructiveHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by concise, high-value behavioral constraints and a compact return format. Every sentence contributes essential information: pool usage, undo relationship, auth requirement, visibility effect, and response shape. Nothing is wasted and no unnecessary examples or filler are included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation tool, the description is complete: it states what the tool does, when to use it, the auth requirement, the API pool it consumes, the effect on the resource, and the return structure. The output schema already exists, but the description still summarizes its key fields, and no critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the comment_id parameter is already described as 'Comment ID to restore (undo discard).' The description does not add extra parameter-level detail beyond the schema, but it also does not need to because the schema already fully documents the single parameter. A baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Restore a previously discarded comment via v2 GraphQL.' It clearly identifies the operation, distinguishes it from the v1 API path, and names its counterpart 'nexus_discard_comment' as the operation being undone. An agent cannot confuse this with the many comment-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool is the 'Undo for nexus_discard_comment' and that it applies to 'a previously discarded comment,' giving a clear condition for use. It also provides a critical exclusion: it requires OAuth Bearer auth and will be denied under apikey-only auth, which helps agents decide whether this tool can be invoked in their current context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral detail beyond the annotations: it clarifies there is no public side effect, that the effect applies immediately, that nexus_get_ignored_users can lag several seconds, and that the return value is either a JSON success object or an error string. These details complement the readOnlyHint, destructiveHint, and idempotentHint annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action, followed by scope clarification, parameter guidance, a timing caveat, and return format. Every sentence earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation, the description covers the operation's purpose, side-effect scope, parameter requirement, timing behavior, and return shape. It also names the related read tool whose results may lag, giving an agent everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents user_id and username individually. The description adds cross-parameter semantics by requiring 'at least one' of them, which is not enforced by the schema's required field list. This is useful but modest given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Stop ignoring (unmute) a user via v2 GraphQL.' It clearly distinguishes this tool from the sibling nexus_ignore_user and the read-side nexus_get_ignored_users, so an agent can identify its role immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: 'Personal preference only: no public side effect' and states the parameter requirement 'Provide user_id OR username (at least one).' It also warns about list-read lag, which is useful for timing. It does not explicitly name alternative tools or when not to use it, but the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish readOnly, idempotent, and non-destructive behavior, and the description adds genuinely useful context beyond that: the endpoint is exempt from hourly rate limits and exposes a rate-limit snapshot. This gives the agent actionable knowledge about side effects and operational characteristics not present in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the primary purpose stated first. Every sentence adds distinct value: what the tool does, what it returns, and when it is safe/useful to call. There is no filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only validation endpoint with an output schema and strong annotations, the description is complete. It covers purpose, return values, rate-limit behavior, and recommended usage, leaving no critical information for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts no parameters, and the input schema confirms this. The description does not need to explain any parameter semantics because there are none, so this dimension is not a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('validate') and a clear resource (the configured Nexus Mods API key), and immediately states the secondary purpose of identifying the account. It also enumerates the returned identity fields, making the tool's function unambiguous and distinct from the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage contexts: checking whether the key works and probing remaining quota via the '_rl' rate-limit snapshot. It also notes the endpoint's exemption from hourly rate limits, making it a safe choice for these checks. It does not name alternatives, but the use cases are clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and idempotent, but the description adds substantial behavioral context: it is backed by the v2 GraphQL API, does not consume v1 REST rate-limit quota, and only resolves GraphQL-originated thread IDs. This goes well beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by important caveats and a clear return shape. Each sentence carries useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
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 complete: it explains scope, alternative usage, ID validity constraints, and return structure. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter is documented in the schema. The description adds essential real-world semantics about which thread IDs are valid, which is not inferable from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Get a comment thread with all top-level comments and their replies.' It also differentiates from the sibling nexus_search_comments by noting that this endpoint is useful where that one is unavailable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use this tool: 'Useful to read replies on threads where nexus_search_comments is unavailable.' It also provides a critical usage caveat about which thread IDs resolve, preventing failed calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide little safety context (readOnlyHint=false, idempotentHint=true with no destructiveHint). The description goes well beyond them by explaining the failure mode (4xx means user revoked the app), the side effect on 4xx (stored tokens are cleared), and the recovery path (log in again). It also discloses the return payload shape. This is exactly the kind of high-value behavioral context the description should add.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact paragraphs with zero filler. The trigger condition is front-loaded, the failure handling and alternative are next, and the return format is last. Every sentence earns its place and the structure aids an agent scanning for when-to-use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete: it covers purpose, invocation trigger, failure semantics, side effects, recovery, and return values. No important behavioral aspect is left to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameter meanings. Returning a baseline of 4 for a zero-parameter tool is appropriate — no semantic gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Force a refresh') and resource ('OAuth access token via the refresh grant'), matching the tool's name and distinguishing it from login/exchange/logout siblings. It unambiguously describes what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use when a request unexpectedly returns 401.' It also gives an exclusion/alternative: on 4xx refresh failure, clear tokens and log in again with nexus_oauth_login, naming the sibling alternative. This is model usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![nexus-mcp MCP server](https://glama.ai/mcp/servers/Talya1412/nexus-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Talya1412/nexus-mcp)

Score Badge

Copy to your README.md:

[![nexus-mcp MCP server](https://glama.ai/mcp/servers/Talya1412/nexus-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Talya1412/nexus-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Talya1412/nexus-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server