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

Annotations already signal that this is a non-read-only, non-idempotent, non-destructive operation, so the bar is lower. The description adds a useful behavioral guarantee that no other fields are modified and mentions that a confirmation is returned, but it does not describe error cases, permissions, or duplicate-note behavior. The added context is meaningful but limited.

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

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

The description is concise and well-structured, with the core purpose front-loaded and an Args list for quick scanning. The Args block largely duplicates schema informationcars, but it is compact and not padded. The 'Returns: Confirmation' line is minimal 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 simple three-parameter mutation tool with fully documented schema and annotations, the description is nearly complete. It explains the operation, the key distinction from field updates, the parameter defaults, and the return expectation. The main gap is the lack of explicit routing guidance toward this tool instead of redmine_update_issue, but overall the definition is sufficient for correct invocation.

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 all three parameters fully. The description's Args section repeats the parameter names, requiredness, and the private_notes default, but it does not add any meaning beyond what the input schema already provides. Baseline 3 is 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 uses a specific verb and resource: 'Add a comment/note to an existing Redmine issue'. The clause 'without changing any other fields' sharply distinguishes it from redmine_update_issue and redmine_create_issue, so an agent can tell what this tool is for even without inspecting the schema.

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

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

The phrase 'without changing any other fields' implies this tool is for adding a note only, not for broader issue editsable, but it never explicitly names alternatives such as redmine_update_issue or states when not to use this tool. Usage context is present but only 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 indicate this is a read-write operation (readOnlyHint=false, destructiveHint=false). The description adds the note that it 'Returns: The created issue details' and provides user-preference handling instructions, but does not disclose any specific behavioral side effects (e.g., notifications, audit trails). No contradiction with annotations.

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

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

The description is a list of parameters that largely duplicates the schema, followed by a lengthy user-preference paragraph that is not central to invoking this tool. It is not concise; the preference block could be moved to a separate context tool, but it is front-loaded with the core action.

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 15 parameters and no output schema, the description is adequate but not comprehensive. It does not explain how to obtain valid IDs (e.g., via redmine_list_projects), nor does it clarify required vs optional fields beyond the schema. The preference instructions are helpful but not directly relevant to creating an issue.

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 input schema covers all parameters at 100%, and the description largely repeats the schema descriptions without adding significant extra context (e.g., how dates are validated, how to resolve IDs). The parent_issue_id mention adds a minor hint for subtasks, but overall the description adds little beyond the schema.

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

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

The description clearly states it creates a new issue in Redmine, with a comprehensive list of supported fields. It is distinct from siblings like redmine_update_issue and redmine_add_note, which serve different purposes.

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 includes an extensive block about user preferences, instructing the agent to ask which projects the user works on and save preferences, but does not explicitly state when to use this tool vs alternatives (e.g., when to update versus create). The preference guidance is useful but tangential to the tool's core usage.

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 create action is implied. The description adds non-obvious behavioral context: the first-time user preference questioning, how to suggest candidates, and the instruction not to ask later. This is valuable beyond annotations. It doesn't contradict annotations, and it transparently discloses a side process the agent must follow.

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 well-structured: a one-line purpose, a clear list of arguments with constraints, a return statement, and a separate paragraph for user preferences. It is front-loaded with the key requirement. While the user-preference section is lengthy, it contains essential operational guidance and is not redundant. The overall length is justified.

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

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

Given the absence of an output schema, the description states 'Returns: Created time entry details,' which is sufficient. It covers the key constraints and the preference workflow. However, it does not specify behavior when both issue_id and project_id are provided (e.g., error or priority), nor does it mention error conditions or permissions. For a create tool with 6 parameters, it is fairly complete but could add a note on exclusivity enforcement.

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 adds meaning beyond the schema: it clarifies the mutual exclusivity of issue_id and project_id ('provide this OR project_id'), and the conditional nature of activity_id ('required unless default exists'). It also paraphrases comments as 'Description of work done' which is slightly more specific. This adds value over the raw schema.

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

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

The description states a clear verb and resource: 'Log time in Redmine.' While it doesn't explicitly distinguish from sibling redmine_update_time_entry, the name 'create_time_entry' and the action of logging time imply creation. The constraint 'Requires either issue_id or project_id' adds specificity. It could be clearer about being for new entries only, but it's still specific 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?

The description provides usage constraints (mutual exclusivity of issue_id/project_id, activity_id condition) and a user-preference workflow (ask once which projects, suggest via redmine_get_current_user, save with redmine_save_preferences). However, it does not explicitly mention when to use this tool versus alternatives like update_time_entry or list_time_entries. The guidance is more about operational setup than selecting the right tool.

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 mark it destructive and non-read-only; the description adds that the action is irreversible and that it returns a confirmation. It does not address edge cases such as deleting a non-existent entry or permission failures.

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 compact and well-structured with separate Args and Returns sections. Every sentence and argument carries informational weight and there is 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 destructive action this is complete: it identifies the required input, warns about irreversibility, and states the return value. An agent has enough information to invoke the tool safely, especially with the annotations already declaring destructiveness.

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

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

Schema coverage is 100% and the description repeats the schema's 'Time entry ID to delete' within the Args block. It adds no additional semantic detail beyond what the schema already provides.

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?

Description uses a specific verb (Delete), resource (time entry), and scope (from Redmine). It is immediately distinct from sibling tools like redmine_update_time_entry and redmine_create_time_entry.

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 guidance is given on when to use this tool, prerequisites, or permission requirements. The only signal is the operation itself, so an agent must infer usage from the tool name and sibling context.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses substantial runtime behavior: bytes are either returned as an image or saved to disk, saved files land in /tmp/redmine-mcp and are configurable via REDMINE_DOWNLOAD_DIR, and there are explicit size limits (10.0 MB saved files, 4.0 MB inline images). No annotation is contradicted.

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 behavior, uses a compact bulleted Args section for the two parameters, and closes with the two most important operational constraints (save location and size caps). Every sentence contributes 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 two-parameter tool with no output schema, the description covers the input source, mode semantics, return behavior (details plus either image or saved path), file location, configuration, and limits. Nothing needed for a correct call is left unstated.

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

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

Even though the schema covers both parameters, the description adds real meaning: attachment_id is sourced from redmine_get_issue with a specific include argument, and mode is explained with concrete auto/image/file outcomes rather than just 'How to return the bytes'. This materially improves correct invocation.

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

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

The description opens with a clear verb-resource pair ('Download a Redmine attachment by ID') and immediately clarifies the mode-dependent outcome, so an agent can tell it from related tools such as redmine_upload_attachment or redmine_get_issue without opening schemas. It is specific and well differentiated.

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 tells the agent where to obtain attachment IDs (redmine_get_issue with include='attachments') and defines exactly when to choose auto, image, or file mode. Although there is no alternate download tool to contrast with, it gives concrete selection criteria and behavioral expectations.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the authentication context ('based on the API key') and clarifies the optional membership data. It does not describe rate limits, error behavior, or the exact structure of the returned user details, but given the annotation coverage, 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?

The description is concise: one main sentence, an Args section for the single parameter, and a Returns line. It is well-structured and front-loaded with the core purpose. There is no fluff, though it could be slightly more formal, but it earns a 4.

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 get operation with one optional parameter and no output schema, the description is adequate. It covers the essential purpose, the parameter's effect, and indicates the return type. It lacks explicit error handling or field details, but given the tool's simplicity and annotation coverage, it is sufficiently complete.

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

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

Schema coverage is 100% with the parameter include_memberships already described. The description goes further by explaining it returns projects and roles, and ties it to a use case (suggesting focus projects). This adds meaningful context beyond the schema's one-liner, so a 4 is warranted.

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 ('Get') and resource ('currently authenticated user'), and clarifies authentication via API key. It is distinct from sibling tools like redmine_get_my_context or redmine_list_users, though it doesn't explicitly name alternatives. The purpose is clear and unambiguous.

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 guidance on when to use this tool versus alternatives. The description does not mention exclusions or prerequisites, nor does it compare with similar read tools like redmine_get_my_context. The only contextual hint is the parameter's use case, not the tool's usage scenario.

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 non-destructive behavior. The description adds useful cross-tool dependency (attachment IDs for download) and explains how include affects the response. No contradictions. It does not cover error behavior or rate limits, but annotations lower the burden.

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 organized with an Args section and is front-loaded with the main purpose. It is a bit long due to field lists, but every part earns its place. No fluff, clear formatting.

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 no output schema, the description compensates by describing what compact and full views return (field lists). It also covers include associations and field overrides. Missing error handling or response format specifics, but for a read tool with strong annotations, it is adequately complete.

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

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

Schema descriptions are minimal (e.g., 'Specific fields to show, overrides view mode'), but the description enriches them significantly: lists available fields, explains compact vs. full field sets, and shows how to use include. This goes well beyond the schema, giving agents a full picture of parameter usage.

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 it retrieves detailed info for a single Redmine issue by ID, clearly distinguishing from list_issues which handles multiple. The verb+resource is specific and the scope (single issue) is explicit. Does not explicitly name the sibling tool but the distinction is implied.

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 concrete guidance on when to use include attachments (needed by redmine_download_attachment) and explains view modes and field overrides. However, it does not explicitly state when to use this vs. list_issues or other alternatives; the context is clear but not explicitly contrasted.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the one-time onboarding instructions and the conditional flow that leads to redmine_save_preferences. It doesn't describe the exact response format, but the onboarding behavior is the key non-obvious trait and it is disclosed.

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

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

Three sentences, all informative, with the core read action first and the conditional onboarding flow second. No filler or repetition of schema/annotation 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?

For a zero-parameter read tool with strong annotations, the description covers the main behavioral nuance (onboarding vs. normal read). It doesn't specify the exact shape of the preferences payload, but no output schema exists and the description's focus on the flow is sufficient for an agent to call it correctly.

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

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

The tool has zero parameters, so there is no parameter semantics burden. The description correctly implies no inputs are needed and focuses on the response behavior. Baseline 4 for zero-param tools is 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 clearly states the tool reads the user's saved Redmine preferences, a specific verb+resource. It also distinguishes itself from the sibling redmine_save_preferences by explicitly mentioning the save flow, so an agent can tell them apart.

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

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

The description gives explicit when-to-use guidance: call it after a save or whenever the user wants to review preferences. It also explains the onboarding path when nothing is saved, including suggesting candidate projects, asking once, and then calling redmine_save_preferences. This is strong routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a return-format note ('Returns: Project details including trackers, categories, etc.') but does not disclose other behaviors such as pagination, error handling, or any requests made to external systems. Since the annotations carry the burden, the description adds moderate value, consistent with a 3.

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 short paragraphs with zero redundancy. The first sentence states the core purpose, followed by a structured argument list and a returns line. It is front-loaded and every sentence earns its place. The format is clean and scannable for an AI agent.

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

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

For a simple read-only tool with only two parameters and no output schema, the description is sufficiently complete. It names the required parameter, enumerates the include options, and gives a sense of the response content. Missing details like error scenarios or authentication requirements are not critical given the annotations cover safety and the operation is straightforward. A 4 reflects adequacy without being exhaustive.

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% (both project_id and include have descriptions in the input schema). The description adds value by specifying the allowed values for 'include' ('trackers', 'issue_categories', 'enabled_modules', 'time_entry_activities') and marking project_id as required. This goes beyond the schema's generic description ('Associations to include') and helps the agent construct valid calls.

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 tool's purpose: 'Get detailed information about a Redmine project.' It uses a specific verb and resource, and the word 'detailed' distinguishes it from sibling tools like redmine_list_projects (which likely returns summaries). The return statement further clarifies scope by listing trackers and categories, making it easy to differentiate from other getters like redmine_get_issue.

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

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

Usage guidance is only implicit. The description conveys that this is for detailed project info, but it does not explicitly state when to use it versus alternatives such as redmine_list_projects or redmine_get_issue. No exclusions or conditions are mentioned, so an agent must rely on inference from the name and 'detailed' wording. This meets the 'implied usage' level but lacks the explicit routing that would push it higher.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the return format (table of IDs and names), which is useful. However, it doesn't disclose whether the list is sorted, paginated, or includes disabled activities. With annotations covering the safety profile, a 3 is fair.

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 with zero waste. The first sentence states the purpose with examples; the second states the return format. Everything earns its place.

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

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

For a zero-parameter read-only list tool with annotations covering safety, the description is nearly complete. The only minor gap is not specifying whether the list is exhaustive or ordered, but that's unlikely to affect correct invocation. The output schema is absent, so the return format note is valuable.

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 has zero parameters, so the schema provides no parameter semantics to speak of. The description correctly notes the return format (table of IDs and names), which is the only semantic content an agent needs. Baseline 4 for zero-param tools is 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 clearly states the tool's purpose: listing available time entry activity types, with concrete examples (Development, Design, Testing). It distinguishes itself from sibling tools like redmine_list_time_entries (which lists actual time entries) by specifying 'activity types' rather than entries.

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 implies when to use this tool: when you need the set of valid activity types for time entries, likely before creating or updating a time entry. It doesn't explicitly exclude alternatives, but the sibling list makes the distinction clear enough. A 4 is appropriate because the context is clear but no explicit when-not-to-use guidance is given.

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, openWorld, idempotent, and non-destructive behavior, so the description does not need to repeat that. It adds valuable behavioral context by explaining the fallback strategy: it tries the admin API first, then extracts fields from a recent issue if admin access is unavailable. This goes beyond the annotations and informs the agent about potential variation in results.

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 compact and front-loaded: the purpose appears in the first sentence, followed by the fallback behavior and return format. Every sentence earns its place; there is no redundant filler or restated tool name.

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

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

For a zero-parameter read-only tool with rich annotations, the description covers purpose, fallback behavior, and return shape. The only minor gap is that it does not mention what happens if neither the admin API nor a recent issue is available, but for typical use this is sufficient.

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 has zero parameters and schema coverage is 100%, so there is no parameter documentation burden on the description. The description still clarifies what the returned table contains, which is useful given there is no output schema.

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

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

The description opens with a specific verb and resource: 'List custom fields available in Redmine.' It clearly differentiates this tool from siblings like redmine_list_issues or redmine_list_projects, and even previews the output content (ID, name, type info), leaving no ambiguity about what the tool does.

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

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

The description implies the tool is for retrieving custom field metadata from Redmine, and the context of Redmine-wide listing tools makes the intended use reasonably clear. However, it does not explicitly state when this tool should be preferred over alternatives or when it should not be used, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: default view mode with token-saving rationale, full vs compact column sets, available override fields, pagination, sort/date filter syntax, and the stateful first-time user-preference flow. It openly describes side effects on agent behavior, like asking once and saving preferences.

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 longer than average but well-organized into a purpose line, a grouped bullet list of arguments, and a user-preference note. Each section has a clear role; the preference note is wordy but relevant to agent behavior. No filler or repetition is present.

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 15 optional parameters, no output schema, and a rich annotation set, the description goes beyond the minimum: it covers filtering, sorting, view modes, pagination, and even return columns for each view. It also accounts for the user's saved-preference state, which is important for correct first-time behavior. Nothing essential for invoking this tool successfully 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 meaning beyond the schema: it explains '~' for root parent issues, gives concrete sort/date filter examples, details what 'compact' vs 'full' views return, enumerates valid columns for 'fields', and groups filters logically. Some parameter details like 'me' or 'open' values are already in the schema, so the added value is strong but not exhaustive.

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

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

The opening sentence, 'List and filter issues from Redmine,' uses a specific verb and resource, making the tool's purpose immediately clear. It is naturally differentiated from the sibling redmine_get_issue, which retrieves a single issue, and from other list-type tools like redmine_list_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 description implies when to use the tool ('List and filter issues') but never explicitly contrasts it with alternatives or states when not to use it. The user-preference note gives workflow guidance for first-time interactions, but it does not address tool-selection trade-offs among the many sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only that it returns a 'Table of members with roles', which is minimal extra behavioral context. No contradictions with annotations.

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

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

The description is short and front-loaded with the purpose. The use-case sentence adds value. The Args block is slightly redundant with the schema but not wasteful. Overall it's efficient and well-ordered.

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 paginated list tool with full schema coverage and comprehensive annotations, the description covers the essentials: what it lists, why you'd use it, and the return type. No output schema exists, but the return description is sufficient. Nothing critical 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% – limit, offset, and project_id all have descriptions in the schema. The description's Args section repeats this information ('limit / offset: Pagination') without adding syntax, formats, or edge cases. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description states 'List members of a Redmine project with their roles' – a clear verb+resource. It adds a use case ('finding assignee IDs when you don't have admin access to /users.json') that differentiates it from the sibling redmine_list_users, though it doesn't name that sibling explicitly. The purpose is unambiguous and actionable.

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 a specific scenario ('when you don't have admin access to /users.json') that tells an agent when this tool is preferable over alternatives. It doesn't explicitly state when not to use it, but the conditional framing provides adequate guidance for a simple read tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that the return value is a list of priority names and IDs, which is useful but minimal. It does not disclose details like ordering, pagination, or whether the list is sorted by Redmine's internal priority weight, but for a simple enumeration tool this is acceptable.

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

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

The description is two short sentences with no filler. The primary purpose is front-loaded, and the return-value note is separated clearly. Every sentence earns its place.

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

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

For a zero-parameter, read-only enumeration tool with rich annotations, the description is nearly complete. It tells the agent what the tool returns and why to use it. The only minor omission is that it doesn't mention whether the list is ordered by priority weight, which could matter when an agent needs to pick the highest priority, but this is a small gap.

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

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

The tool has zero parameters, so the schema carries no burden. The description adds the key semantic detail that the output contains names and IDs, which is the only information an agent needs to use the result. Baseline 4 for zero-param tools is 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 ('List') and resource ('all available issue priorities in Redmine'), and explicitly frames the purpose as finding priority IDs. It is clearly distinguishable from sibling tools like redmine_list_statuses or redmine_list_trackers, which target different Redmine enumerations.

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

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

The description says 'Use this to find priority IDs,' which gives a clear context for when to call it. It does not explicitly name alternatives or exclusions, but among the sibling list tools, the resource name itself disambiguates sufficiently. A small gap is the lack of an explicit 'when not to use' statement.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that the results are limited to accessible projects and returns a table, which is useful but not a rich behavioral disclosure; no contradictions exist.

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 clearly organized into purpose, arguments, return, and user preferences. However, the user-preference paragraph is lengthy and somewhat tangential to the tool's core operation, adding bulk to an otherwise simple list 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?

The description provides a return type ('Table of projects'), pagination details, and accepted associations. It does not explicitly contrast with redmine_get_project, but for a simple read-only listing tool with fully documented parameters, the essentials are present.

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 schema already documents all three parameters. The description adds minor clarity by noting comma-separated associations and labeling limit/offset as pagination, but it does not add substantial new meaning beyond the schema.

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

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

The description states a specific verb and resource: 'List all accessible projects in Redmine.' It clearly conveys what the tool does and implies scope ('accessible') but does not explicitly contrast with siblings like redmine_get_project or other list_* tools.

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 provides context that this tool lists all accessible projects and mentions pagination, but it does not explicitly say when to prefer it over alternatives such as redmine_get_project. The included user-preference workflow is helpful for context but is not a direct tool-selection guideline.

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 read-only, idempotent, non-destructive nature via readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavior beyond annotations: it returns all available statuses and specifies the return shape as 'List of status names and IDs.'

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 compact: a purpose sentence, a usage sentence, and a returns line. Every sentence adds value and the main action is front-loaded 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 zero-parameter read-only lookup with no output schema, the description provides purpose, usage context, and return shape. Nothing an agent needs to correctly select or invoke this 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?

This tool has zero parameters and the input schema is empty, so schema coverage is complete and there is no parameter semantics for the description to clarify. The zero-parameter baseline of 4 applies 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 available issue statuses in Redmine.' It also gives the functional purpose, 'find status IDs for filtering or updating issues,' which clearly differentiates it from other list_* sibling tools.

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 clear context by saying this is used to find status IDs for filtering or updating issues. It does not explicitly name alternatives or exclusion conditions, but for a simple lookup with no close sibling this is sufficient.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds context by noting that this returns a table of time entries and supports optional filters, which is useful given the absence of an output schema. No contradictions with annotations.

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

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

The description is compact and well organized with a short opener, an Args section, and a Returns line. It is slightly redundant with the input schema, but it remains focused and scannable.

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, fully optional read-only list operation, the description covers the main behaviors: what is listed, which filters apply, pagination, and the return shape. It could add ordering or filter-combination details, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description restates each parameter's purpose but adds little beyond the schema, such as clarifying "me" for the current user, which the schema already includes.

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: "List time entries from Redmine" with optional filters. It clearly differs from the sibling create/update/delete time entry tools and other list tools.

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 implies this is the right tool for querying time entries and lists all relevant filter dimensions. It does not explicitly contrast with sibling tools or state when not to use it, so usage guidance is present but only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. Description adds a return format statement ('List of tracker names and IDs'), but no details on output size, ordering, or permissions.

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 with no filler. Core purpose is front-loaded and the return value is stated succinctly.

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 list tool, the description covers purpose, usage, and return format. Nothing an agent needs to invoke it correctly is missing.

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

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

Tool has zero parameters, so parameter ambiguity is nonexistent. Baseline 4 applies; no schema description needed.

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

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

States a specific verb ('List') and resource ('trackers'), with examples ('Bug, Feature, Task') and a clear use case ('find tracker IDs'), distinguishing it from sibling list tools.

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 explicit usage context ('Use this to find tracker IDs') but does not mention sibling tools or exclusion conditions. Clear enough for an agent to decide when it's relevant.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds the admin privilege requirement and the return format ('Table of users'), which are not in annotations. This is valuable behavioral context beyond the structured 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?

The description is compact and well-structured: a clear purpose sentence, an important usage note, a bulleted arg list, and a return statement. No fluff, everything earns its place. Front-loaded with the core action.

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

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

For a read-only list tool with no output schema, the description covers the essential aspects: purpose, permissions, parameter semantics, and return format. It doesn't mention pagination defaults or error handling, but those are minor given the annotations and schema defaults. It's sufficiently complete for correct invocation.

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 adds meaningful details: 'partial match' for name, includes status 0=anonymous (not in schema), and clarifies limit/offset as pagination. This goes beyond the schema descriptions and compensates for the schema's omission of status 0.

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

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

The description opens with 'List users in Redmine' – a specific verb, resource, and system. It also adds an important scoping constraint (admin vs non-admin) that differentiates it from other listing tools, though no sibling is explicitly named. This is unambiguous and distinct.

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

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

Explicitly states when to use: 'Requires admin privileges for full list; non-admins can use project memberships instead.' This names the alternative (project memberships, which corresponds to redmine_list_memberships) and gives a clear condition. It leaves no guesswork about who should use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns 'List of versions with status and due dates,' which is useful output context. It does not mention authentication, rate limits, or other behaviors, but given the read-only nature, this is adequate.

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

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

The description is a single sentence for purpose, followed by a compact 'Args' and 'Returns' section. Every element is necessary and front-loaded. There is no redundancy or fluff.

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

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

For a simple, read-only list operation with one parameter and no output schema, the description adequately states purpose, parameter, and return content. It could mention pagination or limits, but that is not critical for this straightforward call.

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

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

Schema description coverage is 100%: project_id is documented as 'Project ID or identifier' in both schema and description. The description adds no extra detail (e.g., format, examples). Since the schema fully covers the parameter, baseline 3 applies.

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

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

The description states 'List all versions (milestones) for a Redmine project' with a specific verb, resource, and scope. It clearly distinguishes from other list tools (e.g., redmine_list_projects, redmine_list_issues) by targeting versions specifically. The parenthetical 'milestones' adds clarity.

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 purpose is clear and unambiguous; there is no sibling tool for listing versions, so usage is obvious. However, it does not explicitly mention alternatives or exclusion conditions. The context of needing project versions is sufficient, but it lacks explicit guidance on when not to use it.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true. The description adds valuable behavioral context: merge semantics (omitted fields keep saved values), focusProjects: [] clears the list, IDs are validated against live Redmine before saving, save is all-or-nothing, and teammates are not validated against /users.json. This goes beyond annotations and helps the agent understand side effects and constraints. It doesn't mention rate limits or auth, but the validation and atomicity details are strong. A 4 is justified.

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 well-structured with a clear opening sentence, a 'Merge semantics' note, and a bulleted field list. It is moderately sized but every sentence adds value. The field list is concise and informative. It could be slightly more compact, but the structure is clear and front-loaded with the most important behavioral note. A 4 is appropriate.

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 has 9 parameters, no output schema, and no schema description coverage, the description does a good job of covering the essential semantics. It explains merge behavior, validation, atomicity, and field meanings. It doesn't describe the return value or error cases, but for a preferences-save tool with idempotentHint=true, that's less critical. The description is complete enough for an agent to call it correctly. A 4 is justified.

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 0%, so the description carries the full burden of explaining parameters. The description explains each field group: focusProjects, defaultProjectId/defaultTrackerId/catchAllIssueId, defaultActivityId, teammates, timesheet, contentLanguage. It adds meaning beyond the schema by explaining semantics like 'projects the user works on directly', 'assignee shortcuts', 'workDays: [0=Sun..6=Sat]', and 'overrides the skill's English-only rule'. It doesn't explain defaultActivityName (which appears in schema but not description), but the description covers most parameters. A 4 is 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 clearly states the tool saves the user's Redmine preferences, with a specific verb ('Save') and resource ('the user's Redmine preferences'). It distinguishes itself from siblings by being the only preferences-saving tool among the listed siblings, and it details the fields involved. The merge semantics and all-or-nothing behavior further clarify its purpose.

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

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

The description explains when to use this tool: to save user preferences, and it provides context on how fields behave (merge semantics, clearing focusProjects). It doesn't explicitly name alternatives or exclusions, but the sibling list makes it clear this is the preferences tool. The note about contentLanguage overriding the skill's English-only rule gives usage context. However, it doesn't explicitly say 'use this when the user wants to change preferences' vs alternatives, so a 4 is appropriate.

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 it is a non-read-only, non-destructive, idempotent operation. The description adds valuable behavioral context beyond that: 'Only provided fields will be changed' clarifies partial-update semantics, and 'Returns: Confirmation of update' discloses the response shape. The 'use 0 to unassign' detail for assigned_to_id is another useful behavioral nuance.

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 purpose and key behavior, followed by a compact, scannable Args list and a one-line return statement. Every line earns its place, and the grouping of parameters keeps the description short despite 15 parameters.

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?

The description covers most of what an agent needs: it names the operation, the partial-update behavior, the main parameters, and the return value. However, it omits custom_fields from the Args list (though the schema covers it) and does not address when to prefer this over redmine_add_note or redmine_create_issue, leaving minor gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args list mostly paraphrases the schema, but it does add light value by grouping tracker_id/status_id/priority_id as 'Change tracker, status, or priority' and by noting 'use 0 to unassign'. No significant semantic meaning is added beyond the schema.

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

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

The description opens with 'Update an existing Redmine issue', a specific verb+resource statement that clearly identifies the operation. It also adds the partial-update qualifier 'Only provided fields will be changed', but it does not explicitly distinguish itself from siblings such as redmine_add_note or redmine_create_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?

Usage is only implied by the word 'existing' and the update semantics; there is no explicit statement of when to use this tool versus alternatives. The inclusion of 'notes' as a parameter creates potential overlap with the sibling redmine_add_note, but no guidance is given to disambiguate.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds minimal behavioral context—it notes 'existing' (implying requirement of a valid ID) and lists updateable fields, but does not describe side effects (e.g., timestamp changes) or error handling. Given annotations cover the main traits, 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?

The description is extremely concise: one purpose sentence, a bullet list of parameters, and a one-word return note. It front-loads the core action and avoids redundancy. Every sentence earns its place with zero fluff.

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 update tool with no output schema, the description sufficiently covers the core action and lists updatable parameters. It doesn't explicitly mention that at least one field must be changed (though implied), nor does it describe what happens if the entry is not found—minor gaps. Given the tool's simplicity, this is close to complete but not perfect.

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 each parameter already has a description. The tool description merely lists param names ('hours / activity_id / spent_on / comments') without adding new details like value constraints or format specifics that aren't already in the schema. Since the schema carries the term semantics, the description adds no substantial extra meaning.

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 'Update an existing time entry' which specifies a distinct verb, resource (time entry), and scope (existing). This unambiguously differentiates it from sibling tools like create_time_entry and delete_time_entry without needing to inspect schemas.

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

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

The phrase 'existing time entry' provides clear context that this tool is for modifying an already-created entry, not for creating new ones. It does not explicitly name alternatives or state when *not* to use it, but the purpose is clear enough to guide an agent correctly.

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 mutation implied by readOnlyHint=false, the description discloses a concrete side effect: 'Attaching adds an entry to the issue history'. It also warns about Redmine's file size limit and that the limit is reported. These are useful behavioral traits not present in 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 well-structured: a one-line purpose, a bulleted source choice, an Args list, and two behavioral notes. Every sentence adds useful information without redundancy or fluff.

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 tool with six parameters and conditional constraints, the description covers all necessary invocation details: required fields, mutual exclusion, filename defaults, optional parameters, side effects, and error behavior around file size. No output schema exists, but none is needed for correct usage.

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%, but the description adds critical logic missing from the schema: exactly one of file_path or content_b64 must be provided, filename is required with content_b64, and filename defaults to the basename of file_path. This significantly clarifies how to invoke the tool correctly.

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

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

The description opens with 'Attach a file or image to a Redmine issue', a specific verb-resource statement. It also distinguishes itself from the sibling redmine_add_note by noting that attaching already adds an entry to issue history, so no separate note call is needed.

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 explicitly says 'there is no need to call redmine_add_note separately', giving a clear when-not to use an alternative. It also sets usage expectations with 'Give exactly one source' and the file size caveat, though it does not discuss usage versus the download attachment sibling.

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