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

The description states 'Adding a user who is already a monitor is a no-op — the operation succeeds without creating duplicates,' which asserts idempotent behavior, while the annotations declare idempotentHint=false. Repeated identical calls produce no additional environmental effect per the description, directly contradicting the structured hint.

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?

Front-loads the core action and its effect in the first sentence, then layers behavior, alternative routing, and prerequisites in short scannable paragraphs. No filler; every sentence (notifications, remove_monitor, no-op, prerequisites) carries operational value.

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 2-parameter mutation with no output schema, the description covers the effect of the call, the return shape ('success confirmation object'), duplicate handling, the inverse operation, and how to source both required values. Nothing an agent needs 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.

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

Schema description coverage is 100%, so both parameters (issue_id, username) are already fully documented in the schema, including the login-name vs display-name distinction and the discovery tools. The description's prerequisite section restates the same guidance without adding new semantics, 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+resource ('Add a user as a monitor (watcher) of a MantisBT issue') and immediately explains the consequence (email notifications on updates). It is clearly distinguishable from sibling remove_monitor, 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 explicit when-to-use ('subscribe team members to issue updates without assigning them as the handler'), names the inverse operation with its routing condition ('To unsubscribe a user, call remove_monitor with the same parameters'), and lists prerequisites for obtaining valid issue_id and username values.

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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description does not contradict them. It adds genuine context beyond annotations: the returned note fields, UTF-8 support, markdown stored as-is with renderer-dependent output, and the access-level semantics of view_state.

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?

Purpose is front-loaded, followed by return shape, format caveats, visibility rules, and prerequisites in a logical order. Slightly dense but every sentence carries 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?

With no output schema, the description compensates by enumerating the returned fields (id, created_at, reporter, text, view_state, view_url). It covers prerequisites, format handling, and visibility, leaving only minor gaps such as failure behavior and notification side effects.

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 baseline is 3, but the description adds meaning beyond the schema by explaining that private restricts to reporter-level access or higher while public is visible to all issue viewers, and by restating the UTF-8/markdown contract for text.

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+resource ('Add a note (comment) to an existing MantisBT issue') and immediately distinguishes itself from sibling write/read note tools (list_notes, delete_note). An agent knows exactly what this does.

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?

Provides a concrete prerequisite chain (obtain issue_id from list_issues, get_issue, or search_issues), which is real usage guidance. It does not, however, state when to prefer this over alternatives or any exclusion conditions.

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 declare non-read-only, non-idempotent, non-destructive, and the description goes well beyond that by defining what each relationship type means and how directionality works (A child_of B means A blocks B). It does not disclose failure modes such as duplicate-relationship handling, which is notable given idempotentHint=false, but the added semantic context is substantial.

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?

Front-loaded purpose sentence followed by a scannable type table and two short clarifying notes. Every line carries decision-relevant content; the dash-variant note is a minor nicety but not wasteful.

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 full schema description coverage, the description supplies everything an agent needs: type mapping, directionality, and parameter alternatives. Nothing material to correct invocation 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the explicit directionality mapping and the alias/parent/child semantics clarify what the numeric type IDs actually do to the two issues, which the schema only lists tersely.

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 ('Add') and resource ('relationship between two MantisBT issues'), and the sibling list contains remove_relationship, which this is clearly the inverse of. An agent can distinguish it from every other sibling without opening a 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 clear operational context for performing the add, including the choice between type_id and type_name and the directionality semantics. It stops short of explicitly stating when to prefer this over remove_relationship or how to handle an already-existing relationship, so it is clear context but not 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.

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

Annotations only flag readOnly=false, idempotent=false, destructive=false. The description adds real value beyond them: the auto-creation side effect for unknown tag names, the permission that governs it (tag_create_threshold, default REPORTER), and the tag_attach_threshold gate. It leaves open what happens on re-attaching an existing tag, which matters given idempotentHint=false.

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 compact paragraphs, front-loaded with the core action, then the id/name rule, then the permission requirements. No filler sentences.

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 key operational facts: input forms, creation side effect, and both permission gates. The only gap is duplicate-handling behavior on an already-attached tag.

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. The description goes beyond the schema by clarifying that each tag may be given by id OR name — a disjunction the schema merely lists as two optional-looking properties — and that a non-existent name triggers creation.

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 (attach) plus resource (tags on a specific MantisBT issue), and its scope is immediately separable from the sibling detach_tag. No schema opening required to know 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.

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

Gives clear trigger context (attaching one or more tags to an issue, by id or name) and states the permission thresholds that gate the call. It does not explicitly name alternatives or when-not-to-use, 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?

Annotations declare the write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description only needs to add context, which it does: required vs optional fields, defaults for priority/severity, and the server-side resolution of handler. It stops short of describing failure modes (e.g. invalid category or duplicate issues), so not a full 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?

Front-loads purpose and return shape, then organizes the workflow as a short numbered list and the field rules as compressed sentences. Slightly long overall, but no sentence is filler given the 16-parameter surface.

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 creation tool with no output schema, the description covers the essentials: required fields, defaults, return payload contents, dependency tools for resolving foreign keys, and assignee field preference. Nothing an agent needs 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 coverage is already 100%, so the baseline would be 3; the description adds real value by noting that priority/severity accept canonical English names or localized labels and by steering the agent to prefer handler over handler_id. It does not add syntax beyond the schema for the remaining fields, so it is good but not exhaustive.

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 ('Create a new MantisBT issue') and immediately enumerates what the returned object contains, distinguishing it clearly from read/update/delete siblings like get_issue, update_issue, and delete_issue.

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 numbered workflow (resolve category via get_project_categories, versions via get_project_versions, assignee via find_project_member) and a concrete preference rule for handler vs handler_id when working interactively. Also names get_issue_enums for localized enum values.

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 non-read-only, non-idempotent, non-destructive. The description goes further by disclosing the required access level (manage_project_threshold / manager) and the uniqueness side effect, which the annotations do not convey. It does not cover error behavior on name collisions 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.

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

Three short paragraphs, front-loaded with the action, then constraints, then permission requirement. Every sentence carries information; nothing is repeated from the schema or annotations.

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 6-parameter mutation tool with no output schema, the description names the returned fields inline, states the auth requirement, and flags the uniqueness constraint and default. Nothing essential to correct invocation 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 coverage is 100%, so the baseline is 3, but the description adds the cross-parameter constraint that names must be unique within the project and explains the timestamp default behavior — meaning beyond what the schema documents.

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+resource ('Create a new version in a MantisBT project') and immediately distinguishes itself from siblings like update_version, release_version, and delete_version by naming the created object and its scope.

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

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

Gives prerequisites (manage_project_threshold, MantisBT default: manager) and a constraint (unique names per project), which implies when this tool applies. However, it never explicitly contrasts creation with update_version/release_version or states when not to use it, so routing guidance stays implicit.

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 idempotentHint=true, so the safety profile is structured data. The description reinforces permanence/irreversibility, which adds emphasis but no new behavioral facts such as permission requirements or side effects on attached notes/files.

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, zero waste, with the destructive nature front-loaded. Nothing extraneous.

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

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

For a single-parameter destructive tool with annotations covering safety and no output schema, the essentials are present. However, it omits error/permission behavior and what happens to dependent data (notes, relationships), which would be valuable for a delete operation.

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% and there is a single parameter, so the baseline is 3. The description adds nothing about the id parameter beyond what the schema already documents.

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 ('delete') and resource ('MantisBT issue') with a clear scope modifier ('permanently'). It is distinguishable from siblings like delete_note or delete_version by resource, though it doesn't explicitly contrast with them.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative is named. The 'irreversible' note is a warning, not routing guidance, so an agent must infer context on its own.

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 stating irreversibility ('cannot be recovered'), the access-control model (own notes only unless manager-level or higher), and both success and failure return behavior. These are exactly the operational facts an agent needs before a destructive call.

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?

Front-loaded with the destructive action and irreversibility warning, then error behavior and prerequisites. Slightly redundant in restating ID-sourcing already in the schema, but no sentence is wasted.

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 describing the return value ('plain-text confirmation message') and error cases. Combined with 100% schema coverage, nothing needed to invoke this destructive tool 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 coverage is 100% and both parameters are fully documented there, including their sourcing guidance, which the description largely repeats. Baseline 3 applies since the description adds no syntax, format, or constraint 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?

The description opens with a specific verb and resource ('Permanently delete a note from a MantisBT issue'), which cleanly separates it from delete_issue, add_note, and update_issue. 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?

It states a clear prerequisite chain (obtain note_id from list_notes or get_issue notes[].id; issue_id from the same source) and error conditions. It does not explicitly contrast with a named alternative, but the context for when to call it is unambiguous.

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 destructive, idempotent, and non-readOnly, but the description adds critical undisclosed behavior: irreversibility, clearing version/target_version/fixed_in_version fields on referencing issues including subprojects, the manage_project_threshold permission requirement, and the 'Version not found' error for inherited versions. This goes well beyond 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?

Front-loads permanence and irreversibility, then side effects, alternative, constraint, and authorization in tightly structured sentences. Every clause earns its place by informing a destructive decision or preventing a misuse.

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 destructive tool with no output schema, the description covers side effects, prerequisites, permission threshold, and an alternative route. An agent has everything needed to invoke it correctly and safely.

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% and both parameters have inline descriptions with discovery hints. The description adds a usage-level constraint about project_id needing to own the version, but no syntax or format detail beyond what the schema provides, 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 the specific verb 'Permanently delete' and resource 'a version of a MantisBT project,' and distinguishes itself from alternatives like update_version. The sibling tools include create_version, update_version, and get_project_versions, and the description makes the distinction explicit.

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?

Explicitly names update_version with obsolete=true as the non-destructive alternative, explains the inherited-version constraint, and points to get_project_versions with inherit=false for listing eligible versions. Provides clear when-to-use and 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.

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

Annotations already disclose readOnly=false, idempotent=true, and destructive=false. The description adds useful authorization context, specifying the threshold constants and defaults for own versus others' tags, which 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.

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

The description is two concise sentences, front-loading the action and then the permission requirements. 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.

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

For a simple two-parameter mutation tool with annotations and no output schema, the description provides enough context: the action, platform, and permission conditions are all covered. Nothing critical for correct invocation 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 issue_id and tag_id are already documented in the schema. The description does not add parameter-level syntax or format details beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: remove a tag from a MantisBT issue. This clearly distinguishes it from sibling tools like attach_tags and list_tags without ambiguity.

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?

It clearly states the permission thresholds required for detaching one's own tags versus tags attached by others. It does not explicitly name alternative tools or when not to use this one, but the usage context is otherwise clear.

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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description goes beyond them by disclosing the caching behavior (local metadata cache when fresh, live API fallback) and the result-count bound, which is genuinely useful context for an agent reasoning about latency and freshness.

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 short, front-loaded sentences with no filler: purpose first, then result bounds and matching semantics, then data-source behavior. Slight redundancy with the schema's own parameter descriptions keeps it from being maximally tight.

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, 3-parameter read tool with a fully covered schema and no output schema, the description covers scope, matching rules, result limits and cache behavior. Only the relationship to the similar get_project_users sibling 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 limit, query and project_id are already fully documented by the schema. The description largely restates those semantics (limit default/max, case-insensitive substring matching) rather than adding new meaning, which matches the baseline 3 when 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 and resource -- search for users with access to a MantisBT project -- plus the three matchable fields (name, real_name, email). The search-by-attribute framing differentiates it from the bulk listing sibling get_project_users even though that sibling is not named.

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?

Provides operational guidance ('omit query to list the first limit users'), which tells the agent one valid mode of use. However, it never states when to prefer this over the closely related get_project_users, nor any prerequisites or exclusions, so the when-to-use reasoning is left implicit.

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 readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description adds the useful fact that multiple options can be fetched at once and what kinds of options exist, but says nothing about permissions, error behavior for unknown option names, or return shape.

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

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

The purpose is front-loaded in one clean sentence, followed by a scannable list of example values. Every line earns its place; the list is slightly long but each entry 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?

For a simple annotated read tool this is largely adequate, but with no output schema the description leaves the returned structure unexplained (e.g. whether values come back as a name-to-value map or raw strings). That gap is minor but real.

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% and the single parameter is documented, so the baseline is 3. The description goes beyond the schema by enumerating concrete valid option names, which is genuinely valuable because the schema declares no enum and would otherwise leave the agent guessing at legal values.

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: 'Retrieve one or more MantisBT configuration options.' An agent can tell this apart from issue-oriented siblings at a glance. It does not explicitly distinguish itself from nearby metadata siblings like get_issue_enums or get_metadata, which keeps it below a 5.

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 enumerated option names, giving the agent a sense of what this tool is good for. However, it never says when to prefer this over get_issue_enums, get_metadata, or get_mantis_version, nor does it state any prerequisites.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds meaningful context the annotations don't: the target identity is derived from the API key rather than a parameter, which explains why the call takes no input.

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 front-loaded sentence with no filler; every word (verb, resource, scoping condition) 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 zero-parameter, read-only call with annotations covering the safety profile and no output schema, this is essentially complete. The only unaddressed detail is what the returned profile contains, which is minor given the tool's simplicity.

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 beyond reinforcing that identity comes from the API key. Baseline of 4 applies for a no-parameter tool.

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 (Retrieve) and resource (profile of the user), and uniquely scopes it to 'the current API key', which separates it from sibling user-oriented tools like get_project_users or find_project_member. It does not explicitly name those siblings, so it falls 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.

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

Usage is implied rather than stated: an agent can infer this is the tool for 'who am I' queries, but the description gives no when/when-not guidance and no alternatives for looking up other users.

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 readOnly, idempotent and non-destructive. The description adds genuinely useful behavior: notes, attachments, and relationships are included in the payload, and the select parameter can drop those fields. It doesn't mention pagination or response shape, but for a read tool this is solid added context.

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

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

Three short sentences, front-loaded with the core purpose, then the notable return behavior. Every sentence carries information with no 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?

No output schema exists, so the description compensates by describing the returned contents (notes, attachments, relationships) and the effect of select. An agent has what it needs to call and interpret the tool.

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

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

Schema coverage is 100%, so both id and select are already fully documented, including that select is a server-side projection reducing response size. The description only restates that select suppresses fields, adding little beyond the schema. Baseline 3.

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 (Retrieve) and resource (a single MantisBT issue by numeric ID), and clarifies it is the singular counterpart to the list_issues/get_issues siblings. An agent can distinguish it from list_issues and list_notes without opening a 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?

Clearly implies the fetch-one-issue context and explicitly routes the agent away from a separate list_notes call. It does not state exclusions or when to prefer get_issues over this tool, but the single-vs-list distinction is evident.

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 readOnly/idempotent/non-destructive, but the description adds substantial context: the exact response shape, the meaning of id/name/label/canonical_name, which value forms create_issue vs update_issue accept, and the edge case where DB-level customization makes 'name' localized with no 'label'. This is rich disclosure 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.

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

Front-loaded purpose and usage, then structured field notes. The two full example responses are lengthy, but they earn their place by contrasting English vs localized output, which is the tool's main subtlety. Slightly verbose but not wasteful.

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, so the description must carry the return contract — and it does fully: definitions of all fields, example responses, and the customization edge case. An agent has everything needed to call it and interpret results correctly.

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?

Zero parameters, so the schema carries no burden and the baseline is 4. The description instead documents the semantic contract of the returned values (which forms are accepted by downstream tools), which is the relevant guidance for a no-argument lookup tool.

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: 'Return valid ID, name, and (if available) localized label for all issue enum fields.' An agent can clearly distinguish this lookup tool from siblings like get_issue, get_issue_fields, and get_metadata 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.

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

Explicitly states when to use it ('before creating or updating issues') and which fields it covers (severity, status, priority, resolution, reproducibility), and names the downstream tools create_issue and update_issue with how to pass values to each. No inference required.

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?

Beyond the readOnly/idempotent annotations, the description discloses the discovery mechanism (fetching a sample issue reflecting the server's active configuration), the merge step with fields MantisBT omits when empty, and the cache TTL behavior. These are non-obvious operational traits an agent cannot infer from the schema or annotations.

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, front-loaded with the return value, then mechanism, then imperative usage instruction. No filler; every sentence 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?

There is no output schema, but the description states what is returned (field names) and the imperative guidance tells the agent how to use the result. For a one-parameter read-only discovery tool, nothing material 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% and the single parameter project_id is already documented there as 'scope the sample issue fetch'. The description only alludes to this indirectly ('sample issue fetch') and adds no format, default, or scoping semantics beyond the schema, so 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 names a specific artifact ('all field names valid for the "select" parameter') and the exact sibling tools that consume it (list_issues, get_issue), so an agent can immediately tell what it returns and why it exists. This distinguishes it cleanly from get_issue/list_issues, which fetch actual issue data rather than schema metadata.

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?

It gives explicit when-to-use guidance: 'Use this tool before constructing a "select" string.' That is a clear trigger condition tied to a concrete workflow. It lacks explicit when-not / negative guidance, but the positive routing is unambiguous.

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 cover the safety profile (readOnly, idempotent, non-destructive); the description adds real operational traits: parallel execution capped at 5 concurrent, per-position null on 404/403/error, and the guarantee that the call never fails on individual misses. This is exactly the extra context an agent needs before selecting it.

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?

Four tightly packed sentences, front-loaded with what the tool does, then execution model, then failure semantics, then response shape. No filler.

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 correctly compensates by naming the requested/found/failed counters and the null-per-position convention. Nothing an agent needs to invoke or interpret the result 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 coverage is 100% and includes the 1–50 range and null-on-error note, so the baseline is 3. The description reinforces the array-position-to-null correspondence and the concurrency cap, adding a little meaning beyond the raw 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 (retrieve), resource (MantisBT issues), and scope (multiple, by numeric IDs, single call), which cleanly distinguishes it from the singular sibling get_issue.

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 phrase 'in a single MCP call' clearly signals batch-fetch context, and the 1–50 ID cap plus per-position null behavior implies when this is preferable over repeated get_issue calls. It stops short of an explicit 'use get_issue for a single ID' routing statement, so no 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 readOnlyHint/idempotentHint and no destructiveness, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the version comes from the X-Mantis-Version response header, and the comparison performs an outbound HTTPS request to the GitHub API — an external-network side effect worth flagging for a nominally read-only tool.

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 short sentences with zero filler: the core purpose is front-loaded, then the data source, then the network caveat. 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 zero-required-parameter, single-flag tool with no output schema, the description adequately conveys what comes back (a version, optionally with a latest-release comparison) and where it is sourced. Only the exact shape of the comparison result is unspecified, which is a minor gap given the absence of an output schema.

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% and the single check_latest parameter is already fully documented in the schema. The description restates that the comparison is optional and notes the outbound GitHub request, but adds no syntax or default nuance beyond what the schema provides, 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?

The description gives a specific verb and resource ('Returns the version of the connected MantisBT installation') plus its optional comparison behavior. It is clearly distinguishable from the version-shaped sibling get_mcp_version because the resource is explicitly named (MantisBT vs MCP), though the description never names that sibling directly.

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 would call this to discover the connected server's version, and the optional GitHub comparison hints at a 'is my instance current?' use case. There is no explicit when-to-use/when-not guidance and no routing against the similar get_mcp_version sibling.

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 readOnlyHint, idempotentHint and destructiveHint, so the agent knows this is a safe, repeatable read. The description adds only the scoping word 'this instance' and nothing about return format or failure behavior; with a zero-parameter, side-effect-free tool there is little else to disclose.

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 front-loaded sentence with no wasted words. It is appropriately sized for a trivial accessor, though it could have spent one clause separating itself from get_mantis_version.

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 zero-parameter informational tool with no output schema, the description is adequate; the return value (a server version string) is self-evident. The only real omission is disambiguation from the sibling get_mantis_version.

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 no parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond what the empty schema already conveys.

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: returns the version of this mantisbt-mcp-server instance. The qualifier 'this mantisbt-mcp-server instance' implicitly distinguishes it from the sibling get_mantis_version, but the differentiation is left for the agent to infer rather than stated.

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?

No explicit guidance on when to use this over get_mantis_version, the closely-named sibling that returns the MantisBT application version. An agent must guess which version it actually wants; the description never routes between them.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the caching layer, the 24-hour TTL, and the fact that a read may trigger an implicit sync. It does not describe the exact response shape, but the counts are enumerated.

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?

Front-loaded with the primary purpose in the first sentence, then cache semantics, then the routing list. Every sentence carries information an agent needs; no filler.

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 naming the returned fields (project/tag counts and per-project counts), and it covers the cache-miss behavior and alternatives. An agent has everything needed to call it correctly.

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 no parameters, so the baseline is 4; there is no parameter syntax the description needs to supply. Nothing in the description misleads about inputs.

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+resource (returns a compact summary of cached MantisBT metadata) and enumerates exactly what the summary contains: project count, tag count, and per-project user/version/category counts. This clearly distinguishes it from get_metadata_full and the individual list_* siblings.

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?

Explicitly states the automatic-sync behavior when the cache is missing/expired (TTL 24h), names sync_metadata as the tool to force a refresh, and routes the agent to the specific alternatives (list_projects, get_project_users/versions/categories, list_tags) for full data.

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 readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavioral context beyond that: the caching model, the 24-hour default TTL, and the automatic sync-on-miss/expiry behavior. It stops short of return-format details, but with annotations carrying the safety profile and no output schema, a 4 is warranted.

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, front-loaded with what the tool returns, then caching behavior, then routing to siblings. No redundant restatement of the title or annotations.

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 zero-parameter read tool with no output schema, the description fully covers what is returned, the caching/TTL semantics, and how it relates to sibling tools. Nothing an agent needs to select or invoke 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There are no parameters to add meaning to, and the description correctly does not invent parameter 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 (Return) and resource (complete raw MantisBT metadata cache) and enumerates exactly what is included: all projects, per-project users/versions/categories, and all tags. The scope is clearly distinguishable from get_metadata (lightweight) and sync_metadata (force refresh).

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?

Explicitly routes the agent: 'Use sync_metadata to force a refresh. For a lightweight overview use get_metadata instead.' Both alternatives and their selecting conditions are named, leaving nothing 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real behavioral value by disclosing that global categories carry a '[All Projects] ' prefix which this tool strips. That transformation is non-obvious and affects what the caller receives. It stops short of pagination or ordering behavior, hence 4 not 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, purpose front-loaded, and the second sentence is a genuine note about output normalization rather than filler. No redundancy.

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?

A simple single-parameter read tool with no output schema and annotations covering the safety profile; the description is nearly complete for that surface. The prefix-stripping note is especially valuable given there is no output schema to reveal it, though ordering/empty-result behavior remains unstated.

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% with a single fully-described project_id parameter, so the schema carries the semantics. The description adds no format or constraint detail beyond what the schema provides, making 3 the correct 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 ('List') and resource ('categories') scoped to a MantisBT project. The mention of 'all categories available for a project' clearly distinguishes it from sibling tools like get_project_versions, get_project_users, or get_issue_enums.

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 rather than stated: the note that returned names 'can be used directly when creating issues' hints at the create_issue workflow, but there is no explicit when-to-use, when-not, or named alternative. Adequate but with a clear gap.

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 readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds the return shape and a prerequisite (project_id from list_projects), which is useful context beyond the annotations, though it says nothing about ordering or pagination behavior for large projects.

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?

Front-loaded with purpose and return fields, then usage routing, then the access-level table and prerequisite. Slightly redundant in repeating the access-level IDs that the schema already contains, but every block is scannable and 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?

No output schema exists, so the description correctly lists the returned fields (id, name, real_name, email, access_level) and supplies the prerequisite for obtaining project_id. For a two-parameter read 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?

Schema description coverage is 100%, and both parameters are already fully documented including the access-level ID mapping and the "omit to return all users" behavior. The description restates the access-level IDs rather than adding format or edge-case detail, so it does little 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 opens with a specific verb+resource ("List all users with access to a specific MantisBT project") and immediately enumerates the returned fields. It explicitly distinguishes itself from the sibling find_project_member, so an agent can route 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.

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

It states exactly when to use this tool (complete user list, verifying access, building a handler list) and names the alternative for single-user lookup, including why that alternative is preferable (case-insensitive substring search, faster on large projects).

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes beyond them by disclosing non-obvious default filtering behavior (obsolete and inherited parent versions excluded unless obsolete=true/inherit=true) and the shape of the returned objects. Lacks pagination/size notes, so not a full 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?

Four short paragraphs, front-loaded with the core action and scope before alternatives, flag behavior, and prerequisites. Every sentence carries new information; nothing is redundant filler.

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 read-only list tool with full schema coverage and annotations, this is complete: scope, default filtering, sibling routing, prerequisites, and return fields are all covered. No output schema exists, and the description compensates by naming the returned fields.

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 defaults and meanings of obsolete/inherit/project_id are already documented. The description restates the default-filtering semantics and adds usage context for the returned names, but adds no syntax or format 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.

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

Specific verb+resource ('List all versions defined for a MantisBT project') with the scope made explicit, and it names the create/change/release/delete sibling tools it is not. An agent can distinguish it from get_project_categories or list_projects without opening a 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?

Explicit routing: use create_version/update_version/release_version/delete_version for mutations, and a stated downstream use case (feed version names into create_issue/update_issue fields). It also states prerequisites (project_id from list_projects) and the flag conditions that change scope.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the user-scoping constraint, which is genuinely useful, but says nothing about ordering, pagination, or what an empty result means. With annotations carrying the safety burden, a 3 is appropriate.

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, zero filler, with the scope constraint front-loaded and the downstream usage note last. 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 parameterless read-only list tool with no output schema and annotations covering safety, the description supplies what matters: what is listed, whose view it reflects, and how the IDs are consumed. Minor omissions (ordering, empty-result behavior) are not blocking.

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 has nothing to document and the baseline is 4. The description correctly adds no parameter discussion, which is the right call.

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 all saved MantisBT issue filters') plus the scope ('accessible to the current user'). No sibling tool lists filters, so there is no ambiguity about which tool to select.

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 routes the agent forward: 'Filter IDs can be used with list_issues,' which implicitly tells the agent why to call this tool. It lacks any explicit when-not guidance, but for a no-arg enumeration tool 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.

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuine behavioral detail the annotations cannot: the exact returned object shape (id, filename, size, content_type, download_url) and the empty-array edge case. It omits auth/permission notes, which 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.

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

Front-loaded with the core action, followed by the return contract, then routing guidance. Each sentence carries distinct information with no filler.

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, and the description compensates by specifying the return structure and empty-case behavior. With the one required parameter documented and annotations covering safety, nothing an agent needs to call this 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% and the single parameter (issue_id) is already documented in the schema with type and bounds. The description adds no format or constraint detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List all file attachments of a MantisBT issue') with clear scope. It distinguishes itself from siblings upload_file (adding) and get_issue (full issue details) without the agent needing to open another 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?

Explicitly says when to use it ('inspect or enumerate files attached to an issue') and names two alternatives with the conditions that select them (upload_file to add, get_issue for full details). Routing is unambiguous.

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 cover the safe-read profile (readOnly, idempotent, non-destructive), but the description adds genuinely important behavior: four filters are applied client-side, the tool silently auto-fetches up to 500 issues across pages, and client-side filtering can make a page yield fewer than page_size results. That is context the annotations cannot convey.

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?

Front-loaded with purpose and return shape, then the caveat paragraph, then a tip. Each block earns its place, though the note paragraph and tip could be tightened slightly.

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 14-param read/list tool with no output schema, the description covers return shape, pagination semantics, the non-obvious client-side filtering behavior, and an efficiency tip. An agent has what it needs to call this correctly; only the sibling overlap remains 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it explains why "select" matters (significant response-size reduction), notes that page/page_size refer to the post-filter list, and pairs select with date filters for efficiency. It does not, however, resolve semantics for sort, filter_id, or client-vs-server filter interactions in detail.

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 MantisBT issues") with scope ("with optional filtering") and return shape ("paginated list"). However, it does not differentiate itself from the sibling get_issues, which appears to be an overlapping listing tool, leaving ambiguity an agent must resolve by opening 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?

It gives useful in-tool guidance (use "select" to shrink responses, a date-query tip), but never states when to choose this over get_issue or get_issues, nor any prerequisites. Usage is implied rather than contrasted with alternatives.

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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the agent knows this is a safe, repeatable read. The description adds nothing beyond that — no pagination, caching, or scope caveats — but for a zero-argument read of an installation-level constant there is little behavior left to disclose.

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 that front-loads the verb and resource with zero filler. Nothing to trim and nothing buried.

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, no nested objects, and no output schema, the description covers everything an agent needs to decide and invoke. Only a brief note on the shape of the returned list (e.g., language codes vs. display names) would improve it.

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 no parameters, so the schema-coverage baseline of 4 applies. Nothing in the description is needed to explain inputs, and nothing is missing.

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 all languages supported by the MantisBT installation'), so the agent knows exactly what it returns. It doesn't differentiate from siblings, but no sibling plausibly overlaps with this enumeration, so the omission is low-cost.

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?

There is no explicit when-to-use or when-not-to-use statement, and no alternatives are named. However, the purpose is self-selecting: a zero-parameter, read-only enumeration has no plausible competing tool, so usage is implied rather than ambiguous.

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?

Read-only, idempotent, non-destructive behavior is already covered by annotations, so the description doesn't need to repeat it. It does add a non-obvious data-overlap trait: notes are already embedded in get_issue's response, which prevents a redundant call. It stops short of describing ordering, pagination, or return shape.

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. The purpose comes first and the routing caveat second, which is the right order for an agent scanning for a tool to call.

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

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

For a single-parameter, read-only list tool with no output schema, the description covers what is returned (notes/comments for one issue) and when to reach for it. Output format and ordering remain unspecified, a minor gap for a tool this simple.

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% for the single issue_id parameter ('Numeric issue ID'), so the schema carries the parameter burden. The description adds nothing beyond that, which is the expected baseline when the schema is complete.

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 'notes (comments) attached to a MantisBT issue', with the parenthetical disambiguating the domain term. It also explicitly separates itself from the sibling get_issue, so an agent can pick between them 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?

States the exact condition that selects this tool ('only when you need notes without fetching the full issue') and names the alternative (get_issue) that already returns the same data. This is a complete when-to-use / when-not-to-use routing statement.

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 readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds the useful behavioral detail that results are scoped to the current API user's accessibility, but says nothing about ordering, pagination, or output shape.

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 front-loaded sentence with no filler. The purpose and scope arrive immediately with zero 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 zero-parameter, read-only listing tool whose annotations carry the safety profile, the description covers what an agent needs to select it. A brief note on the returned fields (id/name) would close the remaining gap, but it is minor.

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 cannot be richer and the baseline for a no-param tool is 4. The description adds nothing param-related, but there is nothing to add.

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+resource ('List all MantisBT projects') and adds a meaningful scope qualifier ('accessible to the current API user'). It is clear what the tool does, though it does not explicitly contrast itself with the project-scoped siblings (get_project_users, get_project_versions, get_project_categories).

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?

There is no when-to-use, when-not-to-use, or alternative guidance. The description implies the natural use case of enumerating projects (e.g., to obtain IDs consumed by the project-scoped siblings) but never states it, leaving the agent to infer everything.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real value beyond that: it discloses a fallback path (GET /tags may not exist) and that results can come from a local metadata cache populated by sync_metadata, which affects freshness/staleness expectations.

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?

Front-loads the purpose, then a single short paragraph on the endpoint/cache duality. No filler, though the second sentence could be tightened slightly.

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 simple read-only list tool with no output schema, the description covers purpose, source-of-truth caveat, and dependency. Combined with the fully documented schema and annotations, 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.

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

Schema description coverage is 100% and both pagination parameters are fully documented in the schema, including defaults and max, so the description adds nothing here. 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 all tags defined in the MantisBT installation') with clear scope. It is trivially distinguishable from the tag-mutation siblings attach_tags and detach_tag, which use different verbs.

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 read-only listing purpose, but there is no explicit guidance on when to call this versus get_metadata / sync_metadata, which surface overlapping tag data. The fallback sentence gestures at a relationship with sync_metadata without stating which to prefer.

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 annotations: it explains the two-step API call semantics, the partial-failure contract (release persists even if the follow-up fails, error surfaced in next_version_error), the required access level (manage_project_threshold, default manager), and the inheritance restriction with the exact MantisBT error. This is rich behavioral disclosure an agent cannot infer 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?

Front-loads the core action and optional behavior, then layers failure semantics, constraints, and permissions in order. It is longer than average but every paragraph carries distinct, actionable information; no restated boilerplate.

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, and the description compensates fully by documenting the return shape ({ released } plus next_version/next_version_error). Combined with the failure semantics and permission requirement, an agent has everything needed to invoke and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: next_version's name is used as-is with no automatic numbering, and timestamp defaults to now. These semantics go beyond what the schema states even though the schema already documents the parameters.

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?

Opens with a specific verb+resource: 'Mark a version as released and set its date,' plus the optional follow-up creation. This clearly separates it from sibling tools like update_version, create_version, and delete_version, which all operate on the same resource with different effects.

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?

States the conditional that governs the optional behavior ('The follow-up version is only created when next_version is given') and gives a concrete rule for when this tool is and isn't applicable (inherited versions must go through the parent's project_id). It does not directly contrast against update_version, but the usage context is otherwise clear.

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 readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the mutation/irreversibility profile is covered. The description adds the useful consequence that the user stops receiving email notifications, but it does not mention permission/auth requirements or whether the monitor must first exist, so it goes modestly 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.

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

Two tight sentences with the action front-loaded and the consequence second; nothing is redundant. It is appropriately sized for a simple two-parameter tool.

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 whose safety profile is fully covered by annotations and whose parameters are fully documented in the schema, the description gives enough to call it correctly. Only the absence of sibling routing and permission details keeps it from being fully 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?

Schema description coverage is 100% – issue_id and username are both documented in the schema with types and constraints. The description adds no format or edge-case detail about the parameters, 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 (Remove) and resource (user from the monitor list of a MantisBT issue), and the second sentence clarifies the effect. It is clearly distinguishable from read-oriented siblings, though it never names its natural counterpart add_monitor to sharpen the distinction.

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

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

The description says what the tool does but provides no when-to-use or when-not guidance and no reference to the sibling add_monitor that is its direct inverse. An agent must infer the triggering context entirely.

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, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds a workflow requirement (fetch via get_issue first) beyond the structured data, though it doesn't state whether removal is permanent or requires permissions on top of the hints.

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

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

Two tight sentences, front-loaded with the operation and followed by the prerequisite and the disambiguation. Nothing extraneous.

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 and annotations carrying the safety profile, the description supplies the missing workflow and ID-source context. Only a note on permanence or required permissions is absent, which is minor here.

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, but the description adds genuine meaning by clarifying that relationship_id is the numeric id field of a relationship object and explicitly is NOT the type ID — a distinction the schema wording alone does not make.

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 — 'Remove a relationship from a MantisBT issue' — leaving no ambiguity about the operation. The action is clearly the inverse of the add_relationship sibling, and the MantisBT scope is explicit.

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?

'Use get_issue first to retrieve the relationship IDs' gives an explicit prerequisite workflow, which is exactly the guidance an agent needs before invoking. It stops short of naming exclusions or the alternative add_relationship, but 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.

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

Annotations mark this as a non-readOnly, non-idempotent write, and the description corroborates by explaining it populates a local cache, that the cache lives 24h by default (MANTIS_CACHE_TTL), and the fallback tag-scanning strategy for MantisBT < 2.26. That is meaningful behavioral context beyond the annotations, though it never states that the cache is overwritten or that concurrent runs may interleave.

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?

Front-loaded with the core action, then layered with the fallback behavior and cache TTL. Every sentence carries information the agent would otherwise have to guess; no filler.

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 zero-parameter, no-output-schema mutation tool, the description covers what is fetched, where it goes, how tags are handled, TTL, and when to invoke it. The missing piece is orientation relative to the sibling metadata/list tools, which an agent needs to route correctly.

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 document and the baseline is 4. The description correctly adds no phantom parameter behavior.

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+resource: fetch projects/users/versions/categories/tags from MantisBT and write them into the local metadata cache. The read-then-store semantics are unambiguous. It does not differentiate itself from the sibling get_metadata / get_metadata_full tools, which is the only thing keeping it below a 5.

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?

"Use this tool to refresh stale data" and "useful for getting a complete overview" give clear positive usage context, and the 24-hour cache validity implies the refresh cadence. No alternatives or when-not-to-use conditions are named, 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?

Annotations mark it as non-read-only, non-idempotent, and non-destructive, so the safety floor is covered. The description goes well beyond that: partial-update semantics (only provided fields change, unknown keys rejected), the fact that only listed custom_fields are touched, the status+resolution coupling rule, and behavior of the optional note and dry_run preview. These are non-obvious behavioral traits an agent cannot infer from annotations alone.

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?

Front-loaded with the purpose before the field enumeration, and each section (accepted fields, resolution rule, note handling) carries actionable information. It is long and the field list partly restates the schema's key names, but the added format/enum detail keeps it largely justified.

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, the description covers what gets changed, validation behavior (unknown keys rejected), the status/resolution coupling, note appending, and dry_run preview. An agent has everything needed to invoke it correctly without consulting other tools.

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 baseline would be 3, but the description adds real meaning: it enumerates the allowed field names, gives the status enum values, maps resolution id 20 to fixed/resolved, and clarifies custom_fields only modify listed fields. The dry_run and note_view_state semantics are duplicated from the schema, so it lands just below a 5.

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 first sentence states a specific verb (update), resource (MantisBT issue), and mechanism (partial PATCH), and the wording clearly distinguishes it from create_issue, delete_issue, and add_note in the sibling set. An agent can identify the tool 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?

It gives explicit operational rules ("when resolving an issue, always set BOTH status and resolution") and routes to alternatives: use the `note` parameter to avoid a separate add_note call, and use add_note for a note with no field changes. It also points to get_issue_fields for discovery. This is when-to-use and when-to-use-otherwise guidance, not just context.

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 cover safety (readOnly=false, idempotent=true, destructive=false), and the description adds substantial non-structured behavior: partial-update semantics, the cascading rewrite of version/target_version/fixed_in_version on referencing issues, the released/timestamp coupling, and the exact 'Version not found' error condition for inherited versions.

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?

Four short paragraphs, each front-loaded and dedicated to one concern (core semantics, rename side effect, released/timestamp interaction, ownership/access). No filler sentences despite the density of 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?

Even without an output schema, the description tells the agent the call returns the updated version object, and it covers permissions, inheritance constraints, and cross-field traps. 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.

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

Schema coverage is 100%, so parameter docs already carry the baseline. The description adds genuine cross-field semantics the schema cannot express — that name changes cascade to issues and that setting released=true leaves the date untouched unless timestamp is also passed.

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 ('Update an existing version of a MantisBT project') and immediately scopes it as a partial update. It also distinguishes itself from the sibling release_version tool by contrasting their behavior.

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 when/when-not routing: use release_version if you want released=true plus the date set, use get_project_versions with inherit=false to list alterable versions, and call through the parent project_id for inherited versions. It also names the required access level (manage_project_threshold, default manager).

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 write/idempotent/destructive hints; the description adds substantially more: it discloses that no issue fields or status are touched, that it returns created attachment metadata, and that file_path reads from the server filesystem and is disabled over HTTP unless MANTIS_UPLOAD_DIR is set. This transport/permission context goes well 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.

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

Well front-loaded: purpose first, then the two input modes as structured bullets, then optional fields, then routing to siblings. Slightly long, and filename derivation is stated in both the file_path bullet and the filename param, but the length is justified by the mode-selection complexity.

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 6-param write tool with no output schema, the description covers the critical unknowns: mode selection, defaults, server-vs-HTTP transport limitations, and confirmation that attachment metadata is returned. Nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description still adds real meaning: mutual exclusivity of file_path vs content, when content_type defaults, how filename is derived or overridden, and that content is base64. This maps modes and defaults that the schema only states declaratively.

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?

Starts with a specific verb+resource (upload/attach a file to a MantisBT issue) and immediately scopes behavior, stating it adds the file without modifying issue fields or status. Distinguishes itself from siblings list_issue_files and get_issue explicitly by name.

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, actionable selection rules: 'Provide exactly one of the two input modes,' marks file_path as preferred when the file is on disk, and restricts content to in-memory cases. Names the alternatives (list_issue_files, get_issue) for adjacent tasks.

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