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

Annotations only declare readOnlyHint=false, so the description carries the real burden and delivers: it discloses that tags are site-wide, that brand-new tags require ModDB's user-tags API which is currently disabled (HTTP 503), and that create_missing may therefore fail. That is concrete failure-mode and blast-radius information an agent cannot get from structured fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly packed sentences with no filler, and the constraint on tag names is front-loaded before the create_missing caveat. The opening clause largely restates the title, which is the only minor waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with only a readOnlyHint annotation and no output schema, the description supplies the preconditions, visibility semantics, and known failure mode. What it omits is what a successful call returns or whether partial failures are reported, but that gap is minor given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: it explains the accepted domain for 'tags' (only names from list_tags) and the practical consequence of create_missing (site-wide creation attempts that currently fail).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Add tags to a mod') and distinguishes itself from the tag-reading sibling by naming list_tags as the source of valid names. An agent can tell it apart from update_mod and list_tags without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Makes the precondition explicit: tag names must come from list_tags unless create_missing: true is passed, which effectively routes the agent to call list_tags first. It also explains that existing tags are applied via the mod edit form path the site UI uses. It does not state when to avoid this tool versus update_mod, 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.

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is partly covered. The description still adds real value beyond them: irreversibility and the confirm guard, plus the permission boundary that only your own comments can be deleted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence with a parenthetical carrying the two critical facts (irreversible, confirm: true). No wasted words, and the destructive warning is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter destructive tool with full schema coverage, annotations covering the safety profile, and no output schema, nothing an agent needs in order to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both 'comment_id' and 'confirm' fully documented in the schema. The description restates the confirm requirement but adds no new syntax, format, or constraint detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Delete ... comment') and adds an ownership scope ('one of your own comments') that separates it from edit_comment and reply_to_comment. It is clear and actionable, though it never names a sibling alternative explicitly, which is what a 5 would require.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete usage condition — 'requires confirm: true' — and flags irreversibility, so the agent knows the preconditions before calling. It does not say when to prefer edit_comment over deleting, but for a terminal destructive action the guidance is sufficient.

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

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

Annotations only declare readOnlyHint=false, so the description must carry the behavioral load. It does disclose the key trait: the text replaces existing content entirely, and it flags the permission model (own comment vs moderator). It doesn't address reversibility or failure modes, but the destructive-replacement semantics are the critical detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with zero filler; the ownership/permission constraint and the replace-entirely semantics are both front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter mutation with no output schema, the description covers the essentials: who may edit and what editing does to existing content. Return-value behavior is unspecified, but little else is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented, and the description's note that text is Markdown/replaces content largely mirrors the schema wording. Baseline 3 applies since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (edit) and resource (comment) plus an ownership scope ('one of your own comments'), which separates it from reply_to_comment and list_comments. It stops short of naming a sibling directly, so an agent must infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear authorization precondition: use it on your own comments, or on any comment if you are a moderator. It doesn't explicitly contrast with reply_to_comment ('add new' vs 'modify existing'), so the routing is implied 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.

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description usefully adds that the data is public and what the response contains, but says nothing about rate limits, not-found behavior, or how release pagination interacts with the limit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, the resource and payload front-loaded, and the accepted identifier forms last. No filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description correctly takes on the job of describing return contents (ids, tags, links, stats, releases with versions). It is nearly sufficient for a read tool with full schema coverage and a readOnly annotation, though error/empty-result behavior is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema with examples ('carrycapacity', '5894', '/show/mod/54807'). The description's 'name, numeric id, or URL alias' merely echoes that, adding no new format or constraint detail; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Fetch') and resource ('a mod's public ModDB metadata') and enumerates the returned payload (ids, tags, links, stats, release list). That is far more informative than a restated title, though it never names a sibling such as list_my_mods or update_mod to sharpen the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the lookup tool for a single mod, but there is no explicit when-to-use, when-not-to-use, or alternative (e.g. list_my_mods for the caller's own mods). The identifier-flexibility sentence is parameter help, not routing guidance.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description usefully adds the sort order and the shape of the returned identifiers, but says nothing about pagination beyond the schema's limit, rate limits, or how deleted/hidden comments are treated by default. Adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, zero filler, with the core action and ordering front-loaded ahead of the identifier formats and return-value note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by stating that comment ids are returned and what they feed into. Minor gaps remain around pagination behavior and how to page past the limit, but nothing essential to invoking the tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains the accepted mod identifier forms (alias, numeric id, URL) and the limit/include_deleted semantics. The description restates the identifier forms without adding syntax or edge-case detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List comments on a mod's ModDB page') plus ordering ('newest first'). It is clearly distinguishable from the reply_to_comment, edit_comment and delete_comment siblings, which mutate the same resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the downstream tools that consume the returned comment ids (reply_to_comment, edit_comment, delete_comment), which implicitly defines the workflow context for calling this tool. It does not state when *not* to use it or name an alternative listing tool, 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.

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

The readOnlyHint annotation already establishes this is a safe read, and the description is consistent with it. It adds the useful scoping fact that results are limited to the logged-in account's contributions. However, it says nothing about result size, ordering, or pagination behavior for accounts with many mods.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler: the first establishes what the tool returns, the second tells the agent what to do with the output. Scope is front-loaded before the chaining advice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the description carries the burden of explaining the result shape, and it partially does so by naming 'names/paths' as the useful fields. For a simple zero-arg list tool this is close to sufficient, though a note on whether all contributions are returned at once would close the gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to convey; the baseline for a 0-param tool is 4. The description's mention of 'names/paths' describes return values rather than inputs, leaving this dimension essentially neutral.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the mods the logged-in account contributes to') and anchors it to a concrete UI location on mods.vintagestory.at/home, which removes ambiguity about scope. It is clearly distinguishable from siblings like get_mod (single mod fetch) and list_tags (different resource).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit downstream chaining guidance: use the returned names/paths with get_mod, upload_release, update_mod, etc. This tells the agent when this tool is the right first step in a workflow. It stops short of stating when NOT to use it or what to do if the account has no contributions.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context beyond that: it is scoped to the logged-in account's own notifications and the payload consists of notification events (comments, mentions, releases). It says nothing about pagination, ordering, volume limits, or whether unread state is returned, which matters for a notifications feed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, front-loaded with the scope and resource, then a single practical hint. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-param, read-only list tool with no output schema, the description covers identity scope and the shape of the results, which is what an agent needs to select and call it. It stops short of describing pagination or result ordering, a minor gap for a feed-style endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description's mention of the account scope is the only relevant semantic note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (List) plus resource (ModDB notifications) scoped to the logged-in account, with the notification kinds enumerated (comments, mentions, releases of followed mods). This lets an agent separate it from siblings like list_comments or list_my_mods without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence implies a workflow ('quickest way to find comments awaiting a reply on your mods'), which nudges the agent toward this tool over list_comments for that task. However, it never explicitly states when to use this versus mark_notifications_read or when not to use it, so usage is only implied.

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

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

With readOnlyHint=true already covering the safety profile, the description adds genuine context: the vocabulary is site-wide, only these names exist, and unknown names must be created deliberately. That tells the agent how this tool constrains a subsequent write call, though it omits anything about pagination or caching.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first defines what is returned, the second tells the agent why and when to call it. No filler, and the routing hint to add_mod_tags is placed where it matters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description compensates by naming the returned fields (id, name, color) and the scope (site-wide). For a zero-parameter, read-only list tool this is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema baseline of 4 applies and there is nothing further the description could add about argument semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the site-wide tag vocabulary') and even enumerates the returned fields (id, name, color). It is clearly distinguishable from the sibling mutation tool add_mod_tags, which it names explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete when-to-use instruction ('Check this before add_mod_tags') and explains the constraint that makes it necessary — only existing names are valid. It stops short of stating when-not to use it, so it is strong but not exhaustive.

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

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

The annotation readOnlyHint=false already tells the agent this is a mutation, so the bar is lower. The description adds the dual-mode behavior, but does not disclose whether marking is idempotent, reversible, what happens to already-read ids, or what occurs if both parameters are supplied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with zero waste that front-loads the verb and names both modes compactly. Nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no output schema and only a readOnlyHint annotation, the description covers the what but not the operational edges (param precedence when both are set, error behavior for unknown ids, confirmation of affected count). It is minimally complete rather than fully informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented in the schema (including 'ids from list_notifications'). The description merely restates the same two modes in prose, adding no syntax, format, or precedence information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('mark ... as read') and resource ('notifications') and spells out the two operating modes, ids vs all. It is naturally distinguishable from the sibling list_notifications, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the tool name and description ('mark as read'), and the two modes are stated, but there is no guidance on when to prefer this over list_notifications, whether ids must be unread/owned, or any exclusions. Adequate but leaves routing to inference.

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

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

The description declares a state-changing operation ('refresh the action token'), while the annotation asserts readOnlyHint=true, i.e. no environment modification. That is a direct conflict between the text and the structured safety hint, and the description offers no reconciliation (e.g. whether the refresh is persisted locally/server-side). Per the rubric this is an annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both front-loaded with the highest-value information: what it does first, the operational cue second. No filler, no restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and no output schema, the definition is nearly complete: it tells the agent what is checked, what is refreshed, and what is reported. It stops short of saying what happens on an invalid session (error vs. status payload) or what else the status report contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies the session is taken from configuration rather than arguments ('the configured ... session'), which is the only parameter-relevant fact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verbs (validate, refresh, report) plus a specific resource (the configured Vintage Story ModDB session) and a concrete output (the logged-in account). Nothing here overlaps with the sibling CRUD tools like get_mod or update_release, so an agent can identify it instantly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger condition: 'Run this first when other tools complain about an invalid session' — a real when-to-use rule tied to a failure mode. It does not name a when-not case or a specific alternative tool, 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.

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

Annotations carry only readOnlyHint=false, so the description does real work: it discloses that the text is Markdown converted to HTML and that content must be user-approved due to ModDB anti-spam rules. It stops short of stating auth requirements or whether the reply posts immediately or awaits moderation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no padding; the operation is front-loaded and the content constraint follows immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity write tool with 100% schema coverage and no output schema, the description covers purpose, input format, and content policy. It omits only return/confirmation behavior and permission requirements, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents mod identifier formats, comment_id provenance ('from list_comments'), and Markdown text. The description only restates the Markdown aspect, adding no further parameter meaning beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Post a reply to a comment on a mod's ModDB page'), which naturally separates it from siblings edit_comment and delete_comment. An agent can identify the operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The policy constraint ('Use only user-approved wording') is useful guidance on acceptable content, but there is no when-to-use/when-not-to-use routing, e.g. pointing to edit_comment for revising an existing reply or noting prerequisites. Usage is only implied by the tool's name and purpose.

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

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

Goes well beyond the destructiveHint annotation by disclosing the actual consequence: the release stays visible with a retraction notice, becomes non-editable, and cannot be undone by authors. It also surfaces the confirm:true guard, which is critical for a destructive mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, front-loaded with the action and its effect; every clause (visibility, edit lock, confirm guard) carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description covers the essential outcome and irreversibility. Minor omissions remain, such as what a successful call returns and whether the retraction is reversible by moderators (it only says 'by authors').

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the confirm default and the mod identifier formats. The description reinforces reason and confirm but adds no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb (retract) plus resource (release) and clarifies the semantic with 'mark as broken/withdrawn', which no sibling tool (update_release, delete_comment, etc.) covers. An agent can distinguish it from update_release without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a strong selection condition: irreversible, requires confirm:true, release becomes uneditable. It doesn't explicitly name an alternative (e.g. 'use update_release to change metadata instead'), so routing is inferred rather than stated.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden and it delivers: 'description' fully replaces existing text and 'tags' replaces the whole list, plus a guarantee that unlisted fields (team members, images, status) are preserved. Missing auth/permission or reversibility notes keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, no filler, front-loaded with the scope then the mutation semantics then the replacement caveats. Each sentence earns its place by preventing a distinct class of mistake.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter mutation tool with no output schema and only a minimal readOnly annotation, the description covers the destructive replace behavior that matters most. It omits error/validation behavior (e.g. url_alias letters-only) and permission requirements, leaving a small gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely non-obvious meaning by clarifying replace-vs-append semantics for 'description' and 'tags' and the Markdown format. It does not resolve the description_html precedence or the add/remove ordering beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Update') and resource ('a mod's ModDB page') and enumerates the mutable fields (description, summary, name, URL alias, links, side, tags). The scope clearly separates it from release-oriented siblings like update_release and add_mod_tags.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the key selection condition: use field parameters for full replacement versus add_tags/remove_tags for incremental tag changes. It does not explicitly contrast against sibling tools like add_mod_tags or get_mod, so the routing guidance is strong but not complete.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the burden. It adds genuinely useful behavior beyond the schema: the uploaded file can never be replaced, and version edits are restricted to non-game categories. It lacks auth/permission requirements and error behavior, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, with the mutable-field scope front-loaded ahead of the short cross-field constraint. Nothing is padded or repeated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter mutation tool with no output schema, the description covers the important semantics: what can change, what cannot (the file), and the minimum input requirement. Missing only permission/prerequisite and failure-mode guidance, which is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description restates the 'at least one of' constraint (not enforced by the schema) and the non-game limitation on version, adding marginal value but no syntax or format details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Update) and resource (release) and enumerates exactly which fields are mutable: changelog, game_versions, and version. The parenthetical 'non-game mods only' qualification and the immutability of the uploaded file implicitly separate it from upload_release and retract_release.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete invocation rule — 'Provide at least one of changelog / game_versions / version' — which tells the agent when the call is valid. It does not name sibling alternatives (e.g. use upload_release to change the file) or state exclusions, 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.

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

Annotations only say this is a non-read-only, destructive operation; the description adds the crucial consequences the annotations cannot convey: the uploaded file is irreversible ('cannot be replaced afterwards'), a confirm:true guard is mandatory, and identifier/version may be silently overridden by auto-detection from the zip. That is exactly the extra context a mutation tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, zero filler, and the operation's shape is front-loaded before the constraints and the irreversibility warning. Every sentence carries a distinct piece of decision-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-output-schema mutation tool this covers nearly everything an agent needs: irreversibility, the confirm gate, the file location constraint ('on the machine running this server'), and per-category parameter rules. The only unaddressed area is authentication/precondition expectations, which is a minor gap given the annotations already flag destructiveness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% so the baseline is 3, and the description adds cross-parameter conditional logic the schema does not state: version is required only for non-game-mod categories and ignored for game mods, and game_versions is required for game mods. It reinforces rather than merely restates the confirm requirement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource ('upload and publish a new release') with the scope parenthetically clarified as 'zip in, one release out'. The word 'new' implicitly separates it from update_release and retract_release among siblings, so an agent can route correctly without opening other schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear conditional context: game mods auto-detect identifier/version from modinfo.json and require game_versions, non-game-mod categories require an explicit version, and the build should be verified first. It stops short of naming when to prefer update_release/retract_release instead, so it is strong context rather than full when/when-not routing.

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