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

The description explicitly says re-adding an existing monitor is a no-op that creates no duplicates, which contradicts the annotation idempotentHint=false. Although it usefully discloses email notifications and return shape, the contradiction triggers the score-1 rule.

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 deprecation notice and purpose are front-loaded, and the description is generally efficient. It loses some concision by repeating parameter-discovery guidance already present in the schema.

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 supplies the return shape, notification behavior, and prerequisite lookups. The main gap is the contradictory idempotency statement and the lack of permission/auth context.

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 username are already documented in the schema. The description repeats the same discovery guidance (list_issues/get_issue, get_project/member_query) without adding format or constraint details, 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 gives a specific verb and resource: add a user as a monitor/watcher of a MantisBT issue. It distinguishes this from assigning a handler and explicitly names the replacement sibling, update_issue with add_monitors.

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 when to use the tool: subscribing team members to issue updates without making them the handler. It also front-loads the deprecation path to update_issue with add_monitors and lists the prerequisite lookup tools.

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 already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered; the description adds real value on top by enumerating the returned fields (id, status, view_url) and the default values applied to omitted fields. It stops short of mentioning duplicate-issue behavior or that creation is not idempotent, which is the main residual gap for a mutation 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?

Front-loaded with purpose and return shape, then required fields, then a scannable numbered workflow. Every section is useful, though the sentence about priority/severity accepting localized labels repeats the schema verbatim and could be trimmed.

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

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

For a 16-parameter mutation tool with no output schema, the description supplies the missing return-value contract, the required/optional split, valid-value pointers for the enum-ish fields, and the lookup calls needed to source category, version, and assignee. Nothing an agent needs to invoke it correctly is absent.

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 goes further: it restates the four required fields explicitly, gives the 'sensible defaults' for priority and severity, and resolves the handler/handler_id ambiguity that the schema alone only hints at. The priority/severity enum explanation largely duplicates the schema text, so it is not a full 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?

Opens with a specific verb+resource ('Create a new MantisBT issue') and immediately names the return payload, which separates it cleanly from update_issue, delete_issue, and the get_* siblings. An agent can pick this 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?

Provides an explicit numbered prerequisite workflow (get_project with include:["categories"] before calling, versions, member_query for assignee) and states the handler-vs-handler_id preference for interactive use. This is exactly the when/how guidance the dimension rewards, including the dependency chain that would otherwise cause a failed call.

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?

Annotations already flag destructiveHint=true, but the description adds material context beyond them: irreversibility ('cannot be recovered'), the plain-text confirmation return, and the specific failure conditions (missing note, insufficient permission, manager-level access requirement). That is exactly the extra behavioral burden a destructive tool needs met.

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 verb and the irreversibility warning, then return behavior, then errors, then prerequisites as a labeled line. Every sentence carries distinct information; nothing is padding.

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?

Although there is no output schema, the description explicitly states the success return (plain-text confirmation) and error cases. For a two-parameter destructive tool with full schema coverage, nothing an agent needs to call it safely 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 documented in the schema, so the baseline is 3. The description restates the note_id provenance ('obtain from get_issue') which the schema already says, and adds no new semantics for issue_id or constraints beyond the schema.

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

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

States a specific verb and resource — 'Permanently delete a note from a MantisBT issue' — with no ambiguity. The resource ('note' on an issue) is intrinsically separable from the sibling delete_issue and from note-related siblings like add_note/list_notes, so an agent can select it 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?

Explicitly routes the agent to get_issue to source note_id (notes[].id) and explains the permission model governing who may delete. It stops short of naming a when-not-to-use alternative (e.g., there is no 'use delete_issue instead' style exclusion), but the prerequisite chain is clearly spelled out.

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

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

Annotations already flag destructive and idempotent, but the description goes well beyond them: it discloses the exact cascade (version, target_version and fixed_in_version fields cleared on all referencing issues, including subprojects when versions are inherited), irreversibility, and the access level required (manage_project_threshold, default manager).

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 destructive warning, and every paragraph covers a distinct concern (effect, alternative, ownership constraint, permissions). Slight redundancy with the schema's discovery hints 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?

No output schema exists, but the description covers everything an agent needs before calling a destructive mutation: side effects, irreversibility, an escape-hatch alternative, the inheritance trap, and permission requirements.

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

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

Schema coverage is 100%, so both parameters are already documented. The description still adds real meaning by constraining project_id to the version's owning project and explaining that inherited versions will fail, though its discovery hint for get_project largely repeats the schema's own hint.

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 ('Permanently delete a version of a MantisBT project') and immediately marks it as irreversible. It is clearly distinguishable from its nearest sibling update_version, which it names as the non-destructive alternative.

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 when-not: to retire a version without touching issues, use update_version with obsolete=true. It also states the precondition that the version must belong to project_id itself and that inherited versions must be changed via the parent project, with the exact error MantisBT returns.

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 adds useful behavioral context about cache freshness and live API fallback, though it does not discuss auth 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?

The deprecation warning is front-loaded, followed by purpose, matching behavior, and cache behavior. The description is appropriately sized with no wasted 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?

Given the high schema coverage and read-only annotations, the description is nearly complete for a simple search tool. It could say more about the returned user object fields, but no output schema exists and the core behavior is covered.

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

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

Schema description coverage is 100%, so the schema already documents project_id, query, and limit. The description mostly repeats the schema details, adding only the omit-query listing 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 and resource: search for users with access to a MantisBT project by name, display name, or email. It also names the replacement sibling get_project with member_query, making its deprecated role clear.

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 marks the tool as deprecated, names the alternative (get_project with member_query), and gives the removal version. It also explains the omit-query behavior for listing 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 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds value beyond them by disclosing the exact response payload (no output schema exists) and by explaining the semantic meaning of 'language' and its downstream effects on localization — a non-obvious behavioral trait.

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 first sentence front-loads the purpose and payload; the second is a focused, non-redundant note on the one field whose semantics an agent could easily misread. 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 takes on the job of enumerating return fields and does so fully, including the localization caveat. Nothing an agent needs in order to call or interpret this zero-parameter tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly conveys that no input is needed by framing the result as scoped to 'the current API key'.

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 associated with the current API key') and enumerates the fields returned. This clearly separates it from siblings like get_project_users, find_project_member, and get_project, which operate on other users or projects.

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 paragraph gives concrete usage guidance for the 'language' field: use it as the hint for which language to write issue texts and notes in, and expect localized enum labels. There is no explicit when-not or named alternative, but the implicit context (identify the authenticated caller) 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 already establish read-only, idempotent, non-destructive semantics, yet the description still adds substantial value: the batch response envelope { issues, requested, found, failed }, max 5 concurrency, and the key non-obvious behavior that missing/inaccessible IDs yield null in place rather than failing the whole 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 core purpose, then one paragraph per argument mode, then the projection tip. No filler sentences; the batch failure semantics are stated compactly in a single clause.

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 return-shape disclosure falls to the description, and it delivers both variants including view_url on notes and the null-on-failure rule. Nothing needed 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 coverage is 100%, so the 3 baseline already holds for the id/ids descriptions and the 1–50 bound. The description goes beyond it by stating the exclusive-or constraint operationally and by showing concrete select usage (select: "notes", select: "attachments") that clarifies the projection's granularity.

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 a MantisBT issue) and explicitly covers both the single-ID and batch modes. It does not, however, distinguish itself from the near-identically named sibling get_issues or from list_issues, which an agent must disambiguate on its own.

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?

"Pass exactly one of the two" gives a clear, explicit calling rule, and the select paragraph explains when to use projection. It stops short of naming an alternative tool or stating when to prefer get_issues/list_issues over this one.

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 readOnly/idempotent annotations: discloses the deprecation lifecycle and removal version, shows concrete return shapes for both English and localized installs, and explains the non-obvious installation-level customization case where 'name' itself is localized and no 'label' is present. It also states how each field is consumed downstream (create_issue vs update_issue).

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 deprecation notice, which is exactly right. The two full example responses overlap heavily — the localized example could have been reduced to just the 'status' fragment it already is — so a little length is spent on illustration that a one-line explanation would cover.

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

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

There is no output schema, so the description carries return-value explanation entirely, and it does: sample payloads, per-field meaning, localization caveat, and downstream consumption guidance. Nothing an agent needs to call or interpret this zero-arg tool is missing.

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

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

Zero parameters, so the baseline is 4; the schema is empty and needs no compensation. The description's value-format notes ('pass the canonical English name, the localized name, or the label') apply to sibling tools rather than this one's inputs, but they usefully document the output fields.

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' — and immediately names the sibling that supersedes it (get_issue_schema). An agent can distinguish it from get_issue_schema, get_issue_fields, and get_metadata without opening any schema.

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

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

Gives explicit timing ('use this tool before creating or updating issues') and names lookup targets (severity, status, priority, resolution, reproducibility), plus a deprecation redirect to get_issue_schema. The one gap is the mild tension between 'Deprecated: use get_issue_schema instead' and 'Use this tool before creating or updating issues' — the agent isn't told which wins when both are available.

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, it discloses how results are produced (sample issue fetch reflecting server configuration such as eta/projection/profile toggles), that empty-by-default fields are merged in, and that output is cached with the metadata TTL. These are exactly the operational details annotations cannot carry.

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?

Deprecation and replacement are correctly front-loaded, and each following sentence carries distinct information (scope, discovery mechanism, caching). The discovery paragraph is somewhat dense but not redundant.

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 does explain the content of the return value (field names valid for select) and the caching behavior. It stops short of describing the concrete response shape (list vs. object with metadata), which is the one thing an agent must infer.

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 optional project_id already documents its purpose (scoping the sample issue fetch). The description adds only indirect meaning via the mention of server configuration, 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?

States a specific verb+resource (return all valid field names) and scopes it precisely to the "select" parameter of list_issues and get_issue. It also names its replacement (get_issue_schema) up front, so an agent can tell it apart from the sibling schema tool immediately.

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 before constructing a 'select' string" gives an explicit trigger, and the deprecation line explicitly routes new callers to get_issue_schema. Both when-to-use and the alternative are stated, not implied.

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

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

Annotations already cover the safety profile, and the description adds genuinely new behavior: max 5 concurrent parallel requests, per-ID null on 404/403/error, and a guaranteed non-failing call. It also discloses the response shape ('requested', 'found', 'failed' counters) which is not derivable from annotations or schema.

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 plus a deprecation line, with the most important information (deprecation, then semantics) front-loaded. No filler and every sentence carries distinct content.

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, yet the description explains the array-with-nulls return shape and the counter fields, which is exactly what an agent needs to interpret results. Combined with the behavioral details, nothing essential is missing for a one-parameter read 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% and the single `ids` parameter is already fully documented, including the 1–50 bound and null-per-ID semantics. The description largely restates those facts rather than adding new parameter meaning, 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?

States a specific verb and resource (retrieve multiple MantisBT issues by numeric IDs in a single call) and explicitly distinguishes itself from the singular sibling get_issue. The deprecation banner is front-loaded so the agent immediately knows the status of this tool.

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 migration path — 'use get_issue with ids instead — get_issues will be removed in 2.0.0' — which tells the agent both when to use and when to avoid it. It doesn't discuss the batch-vs-single tradeoff or when batching 2–50 IDs is still preferable today, but the alternatives guidance 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?

Beyond the readOnly/idempotent annotations, the description discloses provenance (discovered from a sample issue, reflecting active server configuration), freshness behavior (cached with the metadata TTL), the fields_source values "cache"/"live"/"static", and the quirk that MantisBT omits empty notes/attachments/relationships fields. This is exactly the behavioral context annotations cannot carry.

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 summary sentence followed by two clearly labeled bullets, each sentence carrying distinct information (valid fields, provenance, enum shapes, canonical_name caveat, and the usage trigger). 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 takes on the burden of describing the return shape: field lists plus per-enum id/name/label/canonical_name. Combined with freshness and provenance details, an agent has everything needed to call it 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?

Only one parameter (project_id) and schema description coverage is 100%, so the schema already explains its purpose. The description mentions sample-issue discovery but never states that project_id scopes which sample issue is used, adding 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?

A specific verb ('Return') and resource (valid fields/enums for issues on this MantisBT server) are stated, with the two payloads (fields, enums) enumerated. It falls short of a 5 because near-duplicate siblings get_issue_enums and get_issue_fields exist and the description never explains how this tool differs from them, even though 'in one response' hints at the combined 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?

'Call it before building a "select" string or before setting enum fields' gives an explicit trigger condition tied to concrete downstream tools (get_issue, list_issues, search_issues, create_issue, update_issue). There are no exclusions or named alternatives, so an agent must infer that get_issue_enums/get_issue_fields are partial substitutes.

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 readOnly/idempotent/non-destructive, and the description adds meaningful context beyond them: the tool may reach out to GitHub for the latest official release when comparing, which is a side effect an agent should know about. It does not describe the shape of the returned version data, but no output schema exists to cover that gap either.

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, deprecation warning front-loaded before any functional detail, zero filler. The most decision-relevant fact appears first.

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 one-parameter read-only tool with full annotation coverage, the definition supplies everything needed: deprecation status, migration target, purpose, and the optional network-dependent comparison behavior.

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 boolean parameter check_latest is fully documented there. The description's phrase 'optionally compares' mirrors that but adds no format or default detail, 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?

States a specific verb (returns) and resource (version of the connected MantisBT installation), plus the optional GitHub comparison. It also names the sibling get_version as its replacement, so an agent can distinguish it from get_version and get_mcp_version without opening any schema.

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

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

Explicitly marks the tool deprecated, names the alternative (get_version) and gives the removal timeline (2.0.0). This is a textbook when-not-to-use-this / use-that-instead instruction.

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 lifecycle context the annotations cannot: the tool is deprecated and will disappear in 2.0.0. It doesn't describe the return shape, but that is minor for a zero-param getter.

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

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

Two short sentences, with the deprecation warning front-loaded ahead of the functional description — the right ordering for a tool an agent should avoid. 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 no-parameter, no-output-schema version getter, the description covers purpose, migration path and lifetime. The only gap is the concrete return type/format (string vs object), which nothing else in the definition supplies.

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 there is nothing to disambiguate and the baseline is 4. The description correctly avoids wasting words on a schema that is an empty object.

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, which scopes it away from get_mantis_version (the MantisBT application version). It does not fully explain how it differs from its named successor get_version, but the deprecation framing makes the relationship clear enough.

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 NOT to use it ("Deprecated: use get_version instead"), names the alternative, and gives a removal timeline (2.0.0). This is exactly the when/when-not/alternative guidance the dimension rewards.

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, and the description adds real behavioral context beyond them: cache-vs-live behavior, the default 24-hour TTL, that the full view is large minified JSON, and that a search_index block appears when semantic search is enabled. Since there is no output schema, this return-shape disclosure carries the load well.

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 one-line purpose followed by compact bullets for detail and refresh, then the conditional search_index note and the hand-offs to siblings. Every sentence carries information an agent needs; nothing is padding.

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-param, read-only cache reader with no output schema, the description covers return shape, size trade-off, staleness rules, and alternatives — enough to call it correctly. Completeness only suffers from the unaddressed overlap with get_metadata_full and sync_metadata.

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 genuinely adds meaning: 'summary' yields concrete fields (cached_at, ttl_seconds, per-project counts) while 'full' is flagged as large minified JSON, and 'refresh' is tied to cache invalidation rather than just 're-fetch'. Slight redundancy with the schema keeps it below 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?

States a specific verb and resource — return the cached MantisBT metadata — and enumerates its contents (projects with users, versions, categories, plus tags). It clearly routes away from get_project and list_tags, but says nothing about the identically-purposed sibling get_metadata_full, so an agent cannot fully resolve which one to call from the purpose statement alone.

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 tells the agent which alternative to use for two cases: single-project lists via get_project with include, and tags via list_tags. It also explains when to set refresh vs. rely on the cache (synced only when missing or expired, 24h TTL). The gap is that it never explains when to prefer this tool over get_metadata_full or sync_metadata, both of which overlap the 'detail: full' option and the 'refresh: true' behavior.

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, and non-destructive annotations, the description discloses cache expiration behavior via a default 24-hour TTL and automatic sync when the cache is missing or expired. It also gives the deprecation lifecycle and removal version, which materially affects agent behavior.

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 deprecation warning is front-loaded, followed by a concise description of returned data, cache behavior, and refresh guidance. Every sentence supplies actionable information for selecting or avoiding the 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?

There is no output schema, but the description adequately explains the returned content as the full metadata cache with all projects and per-project users, versions, categories, plus tags. Combined with the annotations and the zero-parameter schema, the definition is complete for correct invocation or avoidance.

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?

This tool has zero parameters, so there is no tool-specific parameter semantics to explain. The description references detail: "full" and refresh: true only for the replacement get_metadata tool, which is useful but not a parameter of this 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?

The description uses a specific verb and resource: it returns the complete raw MantisBT metadata cache, including projects, users, versions, categories, and tags. It also explicitly names the replacement tool and parameter combination, which distinguishes it from get_metadata and sync_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?

Usage is explicit: the tool is deprecated, should be replaced by get_metadata with detail: "full", and will be removed in 2.0.0. It also states when automatic syncing happens and how to force a refresh with get_metadata refresh: true.

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), yet the description adds real behavioral context beyond them: categories names are stripped of the '[All Projects] ' prefix, users come from the local metadata cache when fresh and no access_level is given, and the access_level filter semantics. These are non-obvious traits an agent could not get from structured fields.

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

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

Front-loaded with the core purpose, then a tight bulleted list where each line carries distinct information. Slightly redundant with schema descriptions in the implies-include notes, keeping it from a 5.

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, and the description compensates by naming the returned fields for master data, categories, users (id, name, real_name, email, access_level) and versions (id, name, released, obsolete, timestamp). Combined with the cache and filtering notes, 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?

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding meaning the schema lacks — the access_level numeric mapping (10=viewer ... 90=administrator), the 'default: none' behavior of include, and the fact that member_query searches three fields. It still repeats the 'implies include' notes already present in the schema.

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

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

States a specific verb and resource ('Get one MantisBT project') and enumerates exactly what is returned (master data plus optionally categories/users/versions). This clearly distinguishes it from list_projects and from the narrower get_project_users / get_project_versions / get_project_categories 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 notes the prerequisite 'obtain project_id from list_projects' and explains how the optional sub-resources are triggered via include. It does not, however, explicitly say when to prefer this aggregated call over the dedicated get_project_users/get_project_categories siblings, leaving that routing to inference.

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

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

Annotations already cover read-only, idempotent, non-destructive safety, and the description adds genuinely non-obvious behavior: the MantisBT API prefixes global categories with "[All Projects] " and this tool strips it so names are usable in create_issue. That transformation is not derivable from schema or annotations, though return shape/pagination is not described.

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 deprecation and alternative in the first line, then a one-line purpose, then a short behavioral note. Every sentence earns its place with zero 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?

Covers deprecation, purpose, alternative, and the prefix-stripping behavior — enough to invoke correctly for a simple single-param read tool. The only minor gap is the exact return structure, which is implied but not stated since no output schema exists.

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

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

Schema description coverage is 100% with a single documented project_id parameter, so the schema carries parameter meaning fully. The description adds nothing about the parameter (e.g., that only the given project's categories plus global ones are returned), 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?

States a specific verb and resource ("List all categories available for a MantisBT project") and immediately distinguishes itself by flagging deprecation in favor of get_project with include: ["categories"]. An agent can tell exactly what it returns and whether to call it at all.

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 this tool is deprecated and names the exact alternative invocation (get_project with include: ["categories"]), including the removal version 2.0.0. This is the strongest possible 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 already declare readOnly/idempotent/non-destructive, so the bar is lower; the description adds genuine value beyond them by disclosing the return shape (id, name, real_name, email, access_level) despite there being no output schema, plus the deprecation lifecycle and required prerequisite. Minor redundancy in restating the access-level ID table, which the schema already carries for the access_level param.

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?

Deprecation warning leads, followed by purpose, return shape, and prerequisites — a sensible front-loaded order with no filler. The access-level ID enumeration is repeated from the schema and could be dropped without loss, costing it the top mark.

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 read tool with no output schema, the description covers everything an agent needs: what it returns field-by-field, how to obtain the required ID, what the access_level values mean, and that the tool is being retired in favor of a specific alternative.

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 project_id and access_level are already fully documented, including the ID-to-role mapping and 'omit to return all users' semantics. The description adds essentially no parameter meaning beyond the schema — 'obtain project_id from list_projects' repeats the schema text verbatim. 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 users with access to a specific MantisBT project") and immediately names the replacement call (get_project with include: ["users"]), so an agent can distinguish it from get_project and get_project_versions without inspecting a schema. The deprecated status and removal timeline are front-loaded.

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 to the alternative tool and the exact argument to use instead, and flags removal in 2.0.0 — a real when-not-to-use instruction. It also states a prerequisite chain (obtain project_id from list_projects), leaving little 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?

Although annotations already declare this as read-only, idempotent, and non-destructive, the description adds substantial behavioral context: default exclusion of obsolete and inherited parent-project versions, the obsolete and inherit flags' effects, and the prerequisites for obtaining project_id. It also lists the returned version fields even though no output schema is provided.

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 deprecation notice is front-loaded, followed by purpose, return fields, related mutation tools, parameter behavior, and prerequisites. The structure is efficient and every paragraph contributes actionable 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?

Given that there is no output schema, the description compensates by listing the returned version object fields. It also covers prerequisites, default filtering behavior, and how the returned names map to issue creation and update 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 input schema already documents project_id, obsolete, and inherit fully. The description reinforces the default filtering behavior, but it largely repeats the schema's parameter documentation rather than adding new syntax or semantic detail beyond it.

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: listing all versions defined for a MantisBT project, and it names the replacement tool get_project with include: ["versions"]. It also distinguishes this read/list operation from version mutation siblings such as create_version and update_version.

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 explicitly says the tool is deprecated and should be replaced by get_project with include: ["versions"], while still explaining when to use the returned version names for create_issue and update_issue. It also gives clear alternatives for version mutation operations.

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 readOnly/idempotent annotations: discloses the X-Mantis-Version header source, the outbound HTTPS call with up to 5 seconds latency, the enumerated status values, and the graceful degradation when MantisBT is unreachable (error field while mcp_server is still returned). This is exactly the behavioral context an agent needs before invoking.

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 and the response shape, then explains the check_latest behavior and failure mode. The inline JSON sketch is slightly bulky but earns its place by documenting an otherwise unstated return 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?

There is no output schema, so the description carries the burden of describing the return value, which it does in detail including the specific keys and the error fallback. Combined with its explanation of the only parameter, 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?

Schema coverage is 100% and the parameter is already documented, but the description adds real meaning: the default of true is restated along with the consequence (GitHub fetch + comparison) and the cost (up to 5 seconds), so the agent understands the tradeoff of setting it false.

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 the version of both the mcp-server and the connected MantisBT installation, plus a clear response shape. However, sibling tools get_mcp_version and get_mantis_version exist and the description never explains how this combined tool relates to them, leaving differentiation to inference.

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 response description (use it to get both versions at once) and check_latest explains the GitHub comparison behavior. But there is no explicit when-to-use guidance or exclusion versus get_mcp_version / get_mantis_version, which an agent would need to choose correctly between near-identical siblings.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds useful behavior beyond them: the exact shape of returned objects (id, filename, size, content_type, download_url) and the empty-array case. It doesn't discuss pagination or permissions, but neither is really applicable here.

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?

Deprecation and replacement are front-loaded in the first sentence, followed by exactly the return-value detail 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?

For a one-parameter read with no output schema, the description supplies the return structure and empty-result behavior, plus the migration path. Nothing needed to call or interpret it 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 issue_id is documented there as 'Numeric issue ID', so the schema carries the parameter burden. The description adds no extra meaning about the identifier format or scoping, which is the expected 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 and resource (list file attachments of an issue) and immediately names the replacement tool and migration path. An agent can distinguish it from upload_file or get_issue without opening anything else.

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 to use get_issue with select: "attachments" instead and gives a removal version (2.0.0), which is a precise when-not-to-use and alternative directive.

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?

Discloses behavior the annotations do not: assigned_to, reporter_id, status and date filters run client-side, so the tool auto-scans up to 500 issues internally and may set "truncated": true; page/page_size apply to the post-filter list; group_by ignores page/page_size/select and counts up to a 50,000-issue scan cap. This is exactly the operational context annotations cannot carry.

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 purpose, then organized into Note and Tip blocks covering distinct concerns. It runs long across three paragraphs, but each block addresses a real pitfall (client-side filtering, truncation, group_by output), so little is padding.

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 15-parameter tool with no output schema needs the response shape explained, and the description supplies it for both modes: a paginated issue list and the { group_by, total, groups } structure. Truncation signaling is covered for both paths, leaving nothing an agent must guess before calling.

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; the description goes further by clarifying that page/page_size index the filtered result set (a subtle and easy-to-miss semantic), and by documenting the group_by return shape and its interaction with select and pagination.

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 optional filtering, returning a paginated list. It is clear on its own, but it never distinguishes itself from the sibling get_issues, which an agent would have to open both schemas to resolve.

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 concrete routing guidance for sub-modes: use group_by for overviews instead of listing and counting, use select for compact date queries. However, it offers no guidance on when to pick this tool over the sibling get_issues or get_issue, which is the main selection ambiguity an agent faces.

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

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

With annotations already declaring readOnly/idempotent/non-destructive, the description adds real value: the deprecation lifecycle and, critically, the actual response shape ({ strings, language }), which contradicts what the tool name implies. That prevents an agent from assuming it returns an enumerable list. No output schema exists, so this disclosure matters, though a note on error behavior or whether strings is a map would make it complete.

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: the deprecation and replacement come first, followed by the name-accuracy caveat. Every clause carries actionable 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?

For a parameterless, non-destructive read with no output schema, the description supplies the two things an agent needs: a migration path and the true return shape. Nothing required to call or interpret 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?

Zero parameters, so the baseline of 4 applies. There is nothing the description could add about arguments, and it correctly signals the tool is a no-input call by describing the response rather than 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?

Explicitly states what the tool actually does — calls GET /lang and returns the current user's language payload ({ strings, language }) — and warns that the name is misleading. It also names the sibling that supersedes it, so an agent can distinguish it from get_current_user 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?

Front-loads 'Deprecated: use get_current_user (field "language") instead' with a concrete removal version (2.0.0). Both when-not-to-use and the exact alternative are stated, 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 readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds lifecycle behavior (deprecation and removal version) that annotations cannot express, but says nothing about result shape, ordering, or pagination for issues with many notes. Minor gap, hence 4 rather than 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 short sentences with zero filler, and the most decision-relevant information (deprecation + replacement) is front-loaded before the functional description.

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 one-parameter read-only listing tool with a fully documented schema and no output schema, the description covers purpose, safety implications (via annotations), and migration path. The only missing piece is what the returned note objects look like, which matters somewhat since no output schema exists.

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

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

Only one parameter (`issue_id`), and the schema documents it at 100% coverage with a 'Numeric issue ID' description and numeric bounds. The description adds nothing about the parameter, so the schema does all the work — 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 and resource ('List all notes (comments) attached to a MantisBT issue') and parenthetically disambiguates 'notes' as comments. It also declares the tool's deprecation status up front, so an agent immediately knows what it does and that it is legacy.

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 when-not-to-use rule and a named replacement with exact invocation syntax (`get_issue` with `select: "notes"`), plus a removal timeline (2.0.0). This is about as actionable a routing instruction as a deprecated tool can carry.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that, the description adds genuinely useful behavioral context: the data source may be a live REST endpoint or a stale local cache, which affects trustworthiness of results. It doesn't disclose pagination behavior or the shape of a tag object, keeping it from a 5.

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

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

Three short sentences, purpose front-loaded, then the fallback caveat. No filler, and the conditional behavior is stated compactly before the agent would need it.

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

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

There is no output schema, so the description should at least hint at what a tag record contains or how pagination results are ordered/totaled; it does neither. The source-fallback behavior is covered well, but an agent cannot predict the return payload from the definition alone.

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

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

Schema description coverage is 100%, with page and page_size fully documented including defaults and bounds. The description adds nothing about pagination semantics, so the baseline 3 applies — the schema is doing all the work here.

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' — which is unambiguous and distinct from siblings like attach_tags or detach_tag. It doesn't explicitly name a sibling alternative, but no other sibling lists tags, so differentiation is implicit 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?

The description gives the operational condition under which the tool behaves differently: it uses GET /tags if available and falls back to the local metadata cache populated by get_metadata otherwise. That tells an agent the dependency on prior get_metadata/sync_metadata calls, though it stops short of explicit when-to-use-vs-alternative 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 describe it as a non-readonly, non-idempotent operation, and the description adds substantial behavioral context: default timestamp, follow-up version naming behavior, non-atomic two-call behavior, partial-failure semantics, inherited-version restrictions, and required access level.

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 deprecation notice and replacement path are front-loaded, followed by the core behavior and then caveats. Despite its length, each paragraph contributes necessary operational detail and there is no 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?

No output schema exists, and the description still documents the return shape, including next_version_error on partial failure. It also covers permission requirements, inherited-version handling, and how to discover relevant IDs.

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 still adds meaning beyond the schema by explaining that next_version is used as-is without automatic numbering and that it is created as a separate API call whose failure does not roll back the release.

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 action and resource: mark a version as released and set its date, with an optional follow-up version. It also explicitly identifies itself as deprecated and points to update_version, which clearly distinguishes it from the sibling tool.

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 alternatives (use update_version with released=true, timestamp, and optionally next_version), explains when next_version is created, and states that inherited versions must be changed via the parent project. Access requirements and discovery paths are also provided.

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 annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true), the description discloses the return shape ({ success, removed, monitors }), the idempotent behavior when the user is not a monitor (removed=false, no change), and the authorization requirement with error behavior, adding substantial context.

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

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

The description is front-loaded with the deprecation warning (most critical for current use), followed by a clear explanation, return details, and prerequisites. Every sentence is purposeful and no information is redundant.

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?

Given the tool's simplicity (two parameters, no output schema), the annotations and schema together with the description provide complete context: what the tool does, how to use it or not, return values, edge cases, and authorization needs. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description does not add meaning beyond what the schema provides; it reinforces the action but does not clarify parameter formats or constraints further.

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 clearly states the specific action (remove a user) and resource (monitor list of a MantisBT issue), and it distinguishes itself from the sibling add_monitor by focusing on removal and deprecation in favor of update_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?

Explicitly marks the tool as deprecated and directs to update_issue with remove_monitors instead, providing a clear when-not-to-use and alternative. Additionally, it specifies the access level required for removing other users, giving a prerequisite condition.

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 say readOnlyHint=false, idempotent=false and destructiveHint=false; the description explains that it writes to a local cache valid for 24h, consistent with that profile. It additionally discloses a cost/failure mode an agent could not infer: on MantisBT < 2.26 the tag endpoint is absent and tags are collected by scanning all issues across all 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 the deprecation warning, which is the most important information. Slightly redundant tail: "This is useful for getting a complete overview…" and "Use this tool to refresh stale data" restate what the preceding sentences already cover.

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, side-effecting cache-population tool with annotations covering the safety profile, the description covers scope, staleness policy and the legacy-installation fallback. The one gap is that it never says what the call returns (counts, confirmation, errors) and no output schema exists to cover that.

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 semantics to add. The description's mention of MANTIS_CACHE_TTL is useful context but is an environment variable, not a tool argument.

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: fetch projects plus their users, versions, categories and tags from MantisBT into a local metadata cache. The deprecation notice names the replacement (get_metadata with refresh: true), so an agent can route away from it immediately.

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 ("Use this tool to refresh stale data") and when not to (deprecated, superseded by get_metadata with refresh: true). It also gives the cache validity window and the MANTIS_CACHE_TTL override, which determines whether a refresh is needed at all.

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 the write/non-idempotent/non-destructive profile; the description goes far beyond that by disclosing execution order (fields, monitors, note), non-atomic failure semantics (inline notes_error / monitors_error / note_error rather than call failure), and the "do not retry the steps that went through" rule. It also names the access-level thresholds required to add or remove other users as monitors, which annotations cannot express.

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 field list is a scannable bulleted block preceded by the key scope sentence, so it is front-loaded and structured rather than rambling. A little redundancy remains — e.g. "no separate add_note call needed" repeats what the schema's note description already says — but nearly every sentence carries operational 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 7-parameter nested-object mutation with no output schema, the description covers the critical unknowns: step ordering, partial-failure reporting keys, and monitor permissions. It does mention the "monitors" response shape but says nothing about the primary return payload after a successful field update, and dry_run behavior is only documented in the 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 coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: the allowed status name ladder, a concrete resolution example (id 20 = fixed/resolved), the partial-change semantics of custom_fields, and the rule that an omitted note view_state preserves current visibility. Minor gap: dry_run and note_view_state are never mentioned in the description text, leaving those entirely to 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?

Opens with a specific verb and resource ("Update one or more fields of an existing MantisBT issue using a partial PATCH") and immediately scopes the operation as partial rather than a full replace. It then enumerates the accepted field set, so an agent can tell it apart from create_issue, add_note, or add_monitor 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?

Explicitly routes between siblings: use the "note" parameter for a note alongside field changes versus add_note for a note alone, use add_monitors/remove_monitors for watchers, and get_issue_schema to discover custom fields. It also states a conditional rule (always set BOTH status and resolution when resolving) and that "fields" may be omitted for monitor-only calls.

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?

Adds substantial behavior beyond the annotations: renaming rewrites issue version fields including subprojects, released=true does not update the version date, next_version has distinct response and error behavior, and inherited versions are rejected with 'Version not found'. It also discloses the required access threshold. No contradiction with readOnlyHint=false, idempotentHint=true, or destructiveHint=false is apparent.

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 front-loaded with the core action and then organized around side effects, release workflow, response shapes, project scoping, and permissions. It is appropriately detailed for a mutation tool with side effects, but it is somewhat dense and repeats the normal return shape after already stating it in the opening sentence.

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?

Given the eight parameters, side effects, access requirement, and absence of an output schema, the description is complete enough to call the tool correctly. It covers discovery, inheritance restrictions, release behavior, follow-up version creation, error behavior for next_version, and return object shapes.

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?

Although schema coverage is already 100%, the description adds meaningful cross-parameter semantics: timestamp must be passed with released=true to set the release date, next_version is only valid with released=true, and next_version changes the response shape. It also explains that project_id must be the owning project rather than a parent whose inherited version is being referenced.

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 MantisBT project version, with partial-update semantics and return shape. It is clear overall, but it overlaps with the sibling release_version tool by explaining release behavior without naming release_version or disambiguating when to use it instead.

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 strong operational guidance: only passed fields change, releasing requires released=true plus timestamp, next_version creates a follow-up, inherited versions must be changed via the parent project, and manage_project_threshold access is required. It also points to get_project for discovering a project's own versions. The main gap is that it does not explicitly compare with sibling tools such as release_version, create_version, or delete_version.

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, so the safety profile is already covered; the description adds that issue fields/status are untouched and that metadata is returned on success. The server-side filesystem read and its HTTP-transport restriction plus the MANTIS_UPLOAD_DIR configuration requirement are genuinely valuable context not in the annotations. Minor gap: it doesn't warn about duplicate uploads on retry (consistent with idempotentHint=false) or size 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?

Front-loaded with purpose, side-effect scope, and return value, then a clean two-mode block followed by the alternative tool. It is somewhat verbose — the file_path bullet packs transport, config, and naming concerns into one dense sentence — but nearly every clause carries information an agent needs.

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

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

For a six-parameter mutation tool with no output schema, the description covers the required issue_id context, both input modes and their exclusivity, filename handling, MIME defaults, and what 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 baseline is 3; the description earns an extra point by explaining filename derivation from file_path and the override behavior, the content_type default, and the mutual exclusivity of the two input modes. Some of this duplicates schema text ('Preferred', 'Fallback', 'mutually exclusive'), so it is additive rather than transformative.

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 ('Upload a file as an attachment to a MantisBT issue') and immediately scopes the side effect ('without modifying any issue fields or status'). It also distinguishes itself from sibling read/list tools by naming get_issue with select: "attachments" as the way to enumerate attachments.

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 decision rules: file_path is preferred whenever the file exists on disk, content is the fallback for in-memory data, and exactly one must be supplied. It also names the alternative tool for listing attachments and flags that file_path is unavailable over HTTP transport unless MANTIS_UPLOAD_DIR is configured.

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