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 beyond annotations: it explicitly states the tool never downloads files, never changes metadata, and never deletes attachments, and it discloses that Redmine enforces visibility and may return 401/403/404. This is meaningful additional transparency.

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 core action and endpoint appear in the first sentence, followed by parameter constraints, response contents, error behavior, and explicit non-actions. Every sentence earns its place; no filler or repetition of schema details.

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

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

Given the tool's simplicity (one parameter, no nested objects, output schema present), the description is complete. It covers the endpoint, parameter constraint, response contents, error conditions, and non-behaviors. The output schema handles return-value details, so the description need not explain them.

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 fully documents the single parameter (attachment_id as a positive safe integer). The description reinforces this by restating the requirement ('required attachment_id is a positive safe integer') and noting there are no query or include controls, which adds a small amount of context beyond the schema. 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 states a specific verb ('Read'), a specific resource ('one visible Redmine attachment'), and the exact endpoint (GET /attachments/:id.json). It clearly distinguishes this from sibling tools like list_project_files or get_issue by focusing on the attachment resource. The scope ('for the configured API user') adds precision.

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 clearly indicates when to use this tool: to read a single attachment by ID. It does not explicitly name alternative tools for listing attachments or downloading files, but it does state what this tool does not do ('never downloads files'), which helps an agent avoid misusing it. The visibility enforcement and possible HTTP error codes provide context for when the call may fail.

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?

Despite strong annotations, the description adds meaningful behavior: it documents 401/403 failure modes, Redmine's project-visibility filtering, the safe public profile contract, and the explicit exclusion of self-only fields. It also reassures non-mutation, consistent with readOnlyHint and destructiveHint.

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 dense but well-structured, leading with the action and endpoint, then constraints, privacy behavior, and error cases. The final sentence 'This tool never changes Redmine data' is somewhat redundant with the annotations, but the rest of the text 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 read-only tool with one parameter and an output schema, this description is complete: it covers prerequisites, permissions, accepted parameter values, filtering behavior, privacy exclusions, and possible HTTP errors. No important operational context 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% for the single include parameter, so the baseline is 3. The description adds value by explaining that memberships are filtered to projects visible to the requesting user and that no user_id is accepted, which goes beyond the schema's property definition.

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 verb ('Read'), a specific resource ('Redmine user represented by the configured API credentials'), and the exact endpoint ('GET /users/current.json'). It also distinguishes itself from sibling get_user by stating it requires no user_id and returns the authenticated user's profile.

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 establishes when to use this tool: for the current authenticated user, as a non-admin read with no user_id. It mentions the only valid include and the visibility filtering, but it does not explicitly state a when-not case or name an alternative to prefer for fetching other users by ID.

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 reinforces this with 'This tool never changes Redmine data.' It adds a specific behavioral detail about include=journals returning journal history, which goes beyond the schema. It does not mention auth specifics or rate limits, but for a read-only tool the description is sufficiently transparent given the annotation coverage.

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, front-loaded with the primary action and endpoint, followed by a brief behavioral note. Every sentence earns its place; there is no redundant fluff or repetition of schema 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 read-only tool with a simple parameter set and an output schema (mentioned as present), the description covers purpose, parameter constraints, and a key behavioral detail. It does not need to explain return format since the output schema exists, and error handling is not required for a basic read operation. Sibling differentiation is implicit but 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?

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds a useful clarification that issue_id must be positive (already in schema) and highlights the journal history behavior for the include parameter, which adds value beyond the schema. It does not explain each include option's semantics, but the schema already lists them.

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 (Read), resource (one visible Redmine issue), and even the exact API endpoint (GET /issues/:id.json). It distinguishes from siblings like list_issues by explicitly limiting to a single issue, and from get_issue_relation by focusing on the issue itself. The addition of 'for the configured API user' adds precision.

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 clearly implies usage for a single issue retrieval ('Read one visible Redmine issue'), which distinguishes it from list_issues for bulk retrieval. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough for an agent to infer when to use it. The include parameter guidance is also implicit rather than explicit.

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

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

Annotations already mark this as read-only and idempotent, but the description goes well beyond them: it specifies the exact HTTP endpoint, the lack of query/include/undocumented controls, serializer behavior (camelCase, explicit nulls, omitted associations), browser URL handling, permission requirements, possible HTTP 401/403/404 responses, and explicitly states 'This tool never changes Redmine data.' This is rich, non-redundant behavioral disclosure.

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 dense but front-loaded: the core purpose appears in the first sentence, followed by tightly packed operational details. Each sentence earns its place by covering parameters, response shape, URL behavior, permissions, errors, or mutation guarantees. There is no filler or repetition that bloats the definition.

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

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

For a single-parameter read with an output schema and strong annotations, the description is complete. It covers authentication/permission context, expected error statuses, response serialization nuances, non-mutation, and the exact resource path. No critical information an agent needs to call this tool correctly appears to be 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%: issue_category_id is fully described as a positive safe-integer Redmine issue category ID with constraints. The description repeats 'required issue_category_id is a positive safe integer' and ties it to the endpoint path placeholder, but adds no meaning beyond the schema. 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 opens with a specific verb and resource: 'Read one visible Redmine issue category from GET /issue_categories/:id.json.' The singular 'one' and the explicit endpoint clearly distinguish this from the sibling list_project_issue_categories. The title and description align without tautology.

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 clearly implies this tool is for fetching a single issue category by ID, and it provides useful context about permissions and error responses. However, it never explicitly names alternative tools such as list_project_issue_categories or states when to prefer one over the other. Usage 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?

Beyond the annotations, the description discloses authentication expectations ('ordinary API authentication'), visibility constraints on both linked issues, possible HTTP 401/403/404 outcomes, and preservation of Redmine's null/omitted delay. It also states that no data is changed, reinforcing the read-only annotation. No contradiction with annotations exists.

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

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

The description leads with the purpose, then quickly covers the required parameter and behavioral caveats. It is organized and mostly economical, though the final 'never changes Redmine data' sentence largely duplicates the readOnlyHint/destructiveHint 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?

With one well-constrained parameter and an output schema present, the description covers the remaining operational context: visibility rules, auth, error codes, and result contents. It is complete enough for an agent to decide whether to call the tool and to know what to expect.

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

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

Schema coverage is 100%, so the schema already documents relation_id as a positive integer with bounds. The description adds little beyond the word 'safe' and the requirement that the ID be a positive numeric ID; no parameter semantics are missing.

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

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

States a specific verb ('Read'), a precise resource ('Redmine issue relation'), and the exact endpoint ('GET /relations/:id.json'), plus the scope 'one visible ... for the configured API user.' The singularity of the resource and endpoint distinguish it from listing siblings such as list_issue_relations, even though that sibling is not named.

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

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

The description clearly sets the invocation context: use this tool to read a single, visible issue relation by relation_id for the configured API user. It also notes there are no query controls and that visibility is enforced for both linked issues. It does not explicitly name alternatives like list_issue_relations for multi-result needs, so it stops short of the strongest usage 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?

The description goes well beyond the annotations. It confirms read-only, idempotent, and non-destructive behavior as annotations, but adds specific behavioral details: 'preserves explicit nulls and omitted version-dependent fields', 'strips the API key and administrator flag', and 'adds the ordinary-user /my/account browser URL'. It also discloses possible HTTP 401 or 403 responses. This is rich, useful context that annotations do not provide.

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

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

The description is informative but long, containing multiple clauses about field stripping, null preservation, and URL addition. While each sentence adds value, the description is dense and could be front-loaded with the core purpose. The first sentence is clear, but the subsequent details make it wordy. It is not overly verbose, but there is room for better structure.

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 zero parameters, rich annotations, and an available output schema, the description is complete. It covers the endpoint's input expectations, behavioral transformations, error conditions, and safety. The agent has all necessary information to invoke the tool correctly without further inference. The output schema handles return details.

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?

With zero parameters, the schema provides no parameter details. The description compensates by explaining that the endpoint accepts an empty object only and sends no query/include/pagination controls. This is crucial for an agent to know that no parameters are needed and that the tool has no configuration options. The baseline for 0 params is 4, but the explicit statement about the empty object and lack of controls pushes it to 5.

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

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

The description clearly states the tool reads the current user's own Redmine account data from a specific endpoint, and it names the endpoint and HTTP method, distinguishing it from sibling tools like get_current_user and get_user. It is explicit about scope ('current user's own') and action ('Read'), fully differentiating it from other read 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 does not explicitly state when to use this tool versus alternatives, nor does it mention alternatives like get_current_user. It implies it is for reading the current user's account, but an agent might not know when to choose this over get_current_user or get_user. No exclusions are given for 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 declare readOnly, openWorld, idempotent, and non-destructive. The description adds genuinely useful context beyond those: Redmine enforces news and project visibility, and may return HTTP 401, 403, or 404. The 'never changes Redmine data' line repeats destructiveHint=false but serves as reinforcement rather than a contradiction.

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

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

Four front-loaded sentences with no filler; the core purpose leads, followed by parameter notes, error behavior, and a safety statement. Each sentence earns its place. The closing 'never changes data' is slightly redundant given annotations, 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?

With an output schema present, the description need not explain return values. It covers purpose, parameter constraints, error behavior, and visibility limits for a single-item read tool, which is sufficient for correct invocation. Only sibling routing is absent, a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description adds slight value by framing news_id as a 'positive safe numeric ID' (echoing the exclusiveMinimum and MAX_SAFE_INTEGER bounds) and labeling the include associations, but it does not materially expand on 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?

'Read one visible Redmine news item from GET /news/:id.json' states a specific verb, resource, and exact endpoint. The qualifier 'one' cleanly distinguishes this single-item fetch from the sibling list tools (list_news, list_project_news), and 'for the configured API user' pins down the identity context.

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 fetching a specific known news_id, and the visibility/error discussion hints at when it may fail. However, it never names alternatives or states when to prefer this over list_news or list_project_news, leaving the selection decision 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=true and destructiveHint=false, and the description adds useful context: 'for the configured API user', the visibility qualifier, and the explicit guarantee 'This tool never changes Redmine data'. 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 core action is front-loaded in the first sentence, and the final sentence adds value with the safety guarantee. The second sentence largely mirrors the schema, creating slight redundancy, but the overall description remains compact and well organized.

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 an output schema present and read-only annotations covering safety, the description provides everything needed to invoke the tool correctly: endpoint, required parameter, optional includes, user scoping, and non-mutation guarantee. Nothing critical is missing for this low-complexity, two-parameter tool.

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

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

Schema coverage is 100%, so the schema already documents project_id and include meaning. The description restates these semantics ('positive numeric project ID or valid project identifier', 'Optionally include...') without adding format, syntax, or behavioral detail beyond the schema, meriting the 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?

The description states a specific verb and resource: 'Read one visible Redmine project from GET /projects/:id.json'. 'One' differentiates it from list-style siblings like list_projects, and the endpoint plus 'visible' scoping makes the purpose 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?

Clear usage context is provided: the tool reads a single project by ID or identifier, with optional association includes. It doesn't explicitly name alternatives such as list_projects for enumerating all projects, so the when-not guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: it explains permission enforcement, possible HTTP 403, result characteristics (user/group distinction, inherited flags, no admin group links), and confirms no data mutation. This goes beyond annotations and provides valuable safety and error-handling information.

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 structured efficiently, leading with the core purpose, then parameter detail, result specifics, permission behavior, and a final safety note. Each sentence contributes unique information without redundancy, and the length is justified by the richness of context provided.

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 existence of an output schema, the description need not detail return structures. It covers the tool's action, parameter constraints, permission outcomes, and result nuances, making it sufficiently complete for an agent to invoke correctly. Minor omissions like explicit pagination or full output format are covered by the output schema, so this is well-rounded.

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 already fully describes membership_id as a positive safe integer with bounds, and description coverage is 100%. The description repeats 'positive safe integer' and adds that the endpoint has no query parameters, but does not introduce new parameter meaning beyond what the schema 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 explicitly states 'Read one project membership' and identifies the resource and endpoint. It clearly distinguishes itself from the sibling list_project_memberships by specifying it retrieves a single item by ID, making the purpose unambiguous and differentiating from related 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 usage when a single membership is needed by ID and notes it is a non-admin read that may return 403. However, it does not explicitly contrast with list_project_memberships or state when to prefer this tool over others, leaving some selection guidance 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 convey read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: required view_wiki_pages permission, possible HTTP 401/403/404 responses, and confirmation that no Redmine data is changed.

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 dense sentences front-load the core action and endpoint, then cover parameter constraints, include options, permissions, error behavior, and exclusions. Every sentence earns its place with no redundancy.

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

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

With an output schema present, return values need no elaboration. The description covers endpoint, parameters, permissions, error cases, and scope limitations, making it fully adequate 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 the baseline is 3. The description adds value by clarifying the 'safe nonempty' title constraint and noting that the only documented include is attachments, which reinforces the schema enum without repeating it verbatim.

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 ('Read one current project wiki page') and names the exact endpoint. It clearly distinguishes itself from the sibling get_project_wiki_page_version by stating it does not read historic versions.

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 about what this tool retrieves and explicitly excludes historic versions, which routes agents away from the version endpoint. It does not explicitly name the alternative, but the exclusion is concrete enough for correct selection.

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, but the description adds valuable behavioral context: required Redmine permissions (view_wiki_pages plus view_wiki_edits), possible HTTP 401/403/404 responses, and the guarantee that it never reads the history listing or mutates data. This exceeds the annotation baseline.

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?

Five dense, front-loaded sentences cover endpoint, constraints, includes, results, permissions, errors, and side effects without redundancy. Every sentence earns its place, and the most important scoping information 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?

The description is complete for a read-only tool: it specifies the endpoint path, parameter constraints, the only include option, permission requirements, error responses, and confirms no mutation. The presence of an output schema covers return-value details, so 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 coverage is 100%, so the schema already documents all four parameters fully. The description adds some semantics by mapping parameters to the URL path and emphasizing 'safe' positive integers, but these largely restate the schema constraints. It does not meaningfully change how an agent would fill in the parameters.

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

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

The description opens with a specific verb and resource: 'Read one historic project wiki page revision,' which clearly identifies the action and object. It also distinguishes itself from the sibling get_project_wiki_page by emphasizing 'historic' and 'revision,' making its scope unmistakable.

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 clear context: it reads a specific versioned revision, never reads the history listing, and does not change Redmine data. It does not explicitly name an alternative like get_project_wiki_page for current revisions, but the historical vs. current distinction is strong enough that an agent can infer when 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial context beyond this: it explains the endpoint's behavior (sends no query/include/pagination), that it can return built-in roles, that it preserves field order, nulls, and omission of fields on older servers, and that Redmine may return 401/403/404 without exposing the response body. It also explicitly states 'This tool never changes Redmine data,' reinforcing the read-only nature. 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 detailed but every sentence carries meaningful information. It is front-loaded with the core purpose and endpoint, followed by parameter note, usage distinction, response behavior, and error handling. No fluff or redundant statements; it earns its length with actionable details.

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 presence of an output schema, the description does not need to explain return values. It covers authentication, endpoint, parameter constraints, usage distinction, response mapping details, and error behavior. For a single-parameter tool, this is comprehensive and leaves no critical gaps for an agent to call it correctly.

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

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

The schema already provides full description and constraints for role_id (positive integer, maximum, exclusiveMinimum). The description restates 'positive safe integer' which adds little beyond the schema. Since schema coverage is 100%, the baseline is 3, and the description does not introduce new parameter semantics beyond restating what is already known.

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 ('Read'), resource ('one Redmine role'), and the exact endpoint ('GET /roles/:id.json'). It explicitly distinguishes this from the sibling list_roles tool by noting it is not limited to givable project-member roles, which allows an agent to select the correct tool 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?

The description provides explicit guidance on when to use this tool: when a specific role ID is known and the role may be a built-in (Non member or Anonymous) role. It also contrasts with list_roles, clarifies that it accepts ordinary API authentication, and notes what it does not do (no query, include, pagination, or undocumented controls). This leaves no ambiguity about usage context or alternatives.

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

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

Even with readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral context: the exact endpoint, permission requirements, possible 401/403/404 responses, visible custom fields, URL behavior, and an explicit statement that it never changes Redmine data. 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 dense but every sentence contributes: the action and endpoint are front-loaded, followed by parameter, result, permission/error behavior, and safety. There is no filler or unnecessary repetition.

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

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

For a single-parameter read tool with an output schema and strong annotations, the description covers everything needed to invoke it correctly: endpoint, required ID, permission/error behavior, result shape, and side-effect-free guarantee. It is fully complete.

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

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

Schema coverage is 100% and the parameter is well-documented in the schema. The description adds that the ID is 'positive safe numeric' and required, but this mostly restates the schema's exclusiveMinimum and integer type, so it only marginally adds 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 is explicit: 'Read one visible Redmine time entry from GET /time_entries/:id.json for the configured API user.' This names a specific verb, resource, and endpoint, and the singular 'one' clearly distinguishes it from list-oriented siblings like list_time_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 clearly positions this as a single-resource read by ID and notes the configured API user and visibility constraints. It does not explicitly name alternatives or state when not to use it, 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains that Redmine may return 403/404 due to visibility enforcement, that private fields are omitted, and that memberships are filtered to visible projects. It also explicitly states 'This tool never changes Redmine data,' reinforcing the read-only nature. This is strong behavioral disclosure for a read 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?

The description is compact and front-loaded: it opens with the core action and endpoint, then adds parameter semantics, then behavioral caveats, and ends with a clear safety statement. Every sentence earns its place, and there is no redundant repetition of schema or annotation content. It is appropriately sized for the tool's complexity.

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

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

Given the tool's simplicity (2 params, 1 required), the rich annotations, and the presence of an output schema, the description is complete. It covers the endpoint, parameter semantics, visibility/error behavior, field filtering, and read-only guarantee. An agent has everything needed to select and invoke this tool correctly without opening the schema or output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaning by explaining that user_id must be a 'positive safe integer' and by elaborating on the include parameter's behavior: memberships are documented for non-admin callers and filtered to visible projects. This goes beyond the schema's terse descriptions and helps an agent understand the practical effect of the parameters.

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

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

The description states a specific verb ('Read'), a specific resource ('one visible Redmine user'), and the exact endpoint ('GET /users/:id.json'). It also clarifies the scope ('for the configured API user') and distinguishes it from list-style siblings by emphasizing 'one' user. This is unambiguous and clearly differentiates from sibling tools like get_current_user or 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 provides clear context on when to use this tool: to read a single user by ID, with optional memberships inclusion. It does not explicitly name alternative tools or state when not to use it, but the context is strong enough that an agent can infer it is for single-user reads rather than listing or current-user operations. The mention of non-admin behavior and visibility rules adds useful usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explicitly states 'This tool never changes Redmine data,' notes that visibility is enforced by Redmine, and discloses possible HTTP error codes (401, 403, 404). It also explains that estimatedHours and spentHours are included only when Redmine returns them, which is useful conditional behavior. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded: it opens with the core action and resource, then adds route details, parameter constraints, response behavior, and error conditions in a logical order. Every sentence adds value, and there is no repetition of schema or annotation content. It is appropriately sized for the tool's simplicity.

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

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

For a single-parameter read tool with a rich output schema, the description covers everything an agent needs: the route, the parameter, the response fields, visibility/error behavior, and the no-mutation guarantee. The output schema exists, so return values need not be enumerated in the description. The tool is simple, and the description is complete for its complexity.

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 version_id as a positive Redmine version ID. The description adds meaning by specifying that version_id must be a 'positive safe integer' and that the route has no query parameters or include controls, which clarifies the parameter's role and constraints beyond the schema. This is a solid complement 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?

The description states a specific verb ('Read'), a specific resource ('one visible Redmine version'), and the exact API route ('GET /versions/:id.json'). It also clarifies the scope ('for the configured Redmine API user') and distinguishes it from list_project_versions by focusing on a single version by ID. This is unambiguous and clearly differentiated from 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?

The description clearly states when to use this tool: to read one visible Redmine version by ID. It also implicitly distinguishes it from list_project_versions (which lists versions) and other get_* tools. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses several meaningful behaviors: no query/include/pagination controls, preservation of upstream order, explicit field mapping, version-dependent field availability, error behavior with 401/403/404, and the absence of browser links. This is rich, accurate behavior disclosure.

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 dense and front-loaded, with the core purpose in the first sentence and every later sentence adding relevant behavioral or versioning detail. It is somewhat long, and the final sentence ('This tool never changes Redmine data') largely restates the annotations, which costs it a perfect score.

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 read tool with an output schema, this description is unusually complete: it states the endpoint, field mapping, version thresholds, shared-versus-project scope, browser-link absence, error behavior, and mutation safety. 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?

The tool has zero parameters and the schema is empty, so there is no parameter semantics to document. The description still adds useful context by confirming that the endpoint accepts no query, include, or pagination controls, which exceeds the baseline for a zero-parameter tool.

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

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

The description names a specific verb ('Read') and resource ('all shared Redmine document categories') and even identifies the exact endpoint. This clearly distinguishes the tool from siblings like list_issue_categories and list_projects 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 description gives clear contextual scope by explaining that the result is the shared collection, includes inactive categories when Redmine returns them, and excludes project-specific enumeration overrides. It does not explicitly name alternative tools, but no sibling directly competes with this resource, so the context 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?

Goes well beyond annotations by disclosing that the tool never changes Redmine data, that upstream errors may surface as 401/403/404 without response body exposure, and that ordering, custom-field nulls, omitted version-dependent fields, and result mapping have specific behavior. This gives agents practical expectations not available from readOnlyHint/idempotentHint alone.

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

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

The first sentence front-loads the purpose and endpoint, and every subsequent sentence adds operational detail such as ranking order, field mapping, version availability, browser-link absence, and error behavior. It is dense rather than verbose, though a few edge-case details could be considered extra for a zero-parameter tool.

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

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

Covers the endpoint, parameter restrictions, ordering, field mapping, version caveats, upstream error handling, lack of browser links, and non-mutation guarantee. Since an output schema exists, return-value documentation is already covered, and no critical calling guidance appears 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 input schema has zero parameters and schema description coverage is 100%, so the baseline is 4. The description reinforces this by stating there are no query, include, or pagination controls, which helps the agent avoid inventing unsupported options.

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?

Clearly states the verb and resource: 'Read all Redmine issue priorities from GET /enumerations/issue_priorities.json...' and defines scope with 'shared global priorities' and 'lower-to-higher position order.' This distinguishes it from sibling list tools like list_issue_statuses and list_document_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?

Provides clear context by specifying this is a read-only enumeration for the configured Redmine API user and explicitly notes the endpoint accepts no query, include, or pagination controls. It does not name alternatives or direct when-not-to-use conditions, but the resource is unique among the 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 readOnly, idempotent, and non-destructive behavior; the description adds valuable context beyond that: error semantics ('may return HTTP 401, 403, or 404'), Redmine's issue and related-project visibility enforcement, absence of pagination, and that returned links are safe base-path browser links for valid IDs. The closing line 'This tool never changes Reddit data' is consistent with the annotations and reinforces the safety profile.

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 five sentences, slightly longer than strictly minimal, but every sentence carries distinct information: endpoint and scope, input constraint, absence of pagination, response/link behavior, and error/visibility semantics. It is front-loaded with the primary purpose and contains 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-only tool with an output schema that covers return shape, the description is nearly complete: it covers input constraints, mutational safety, auth failures (401), visibility enforcement (403/404), and the out-of-scope behaviors (no filter or pagination). That depth of context is still slightly above what a simple read tool needs.

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 schema already documents issue_id as a positive integer with an exclusive minimum of 0 and a safe-integer maximum. The description repeats 'one positive safe numeric ID,' adding a safety framing but no new format or meaning beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The first sentence states a specific verb ('Read'), an exact resource ('visible relations for one Redmine issue'), and the precise endpoint ('GET /issues/:issue_id/relations.json'). The scope ('one issue', all visible relations, no query controls) distinguishes it from the sibling get_issue_relation, which fetches a single relation. This makes the tool's role unambiguous against the 33 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 situational context: it lists all visible relations for one issue for the configured API user, and explicitly notes the route 'has no query controls or pagination' so an agent knows it cannot filter or page results. It does not explicitly name alternatives like get_issue_relation or state when not to use it, so it stops short of a full exclusions-based 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?

With annotations already declaring readOnlyHint and non-destructive behavior, the description's 'never changes Redmine data' adds little. It does provide useful behavioral context beyond annotations: only issues visible to the configured API user are returned. No error, rate-limit, or pagination behavior beyond what the schema specifies 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?

The description opens with a clear purpose statement and then lists capabilities in a dense, readable second sentence. The final, third sentence about not changing data is redundant given annotations, but the description remains concise and efficient overall.

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 list tool with 15 parameters and a rich output schema, the description provides enough context: the endpoint, scope (visible to API user), and full filter support. It does not explain return format or indicate when to consult siblings, but the output schema and sibling names cover those 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 coverage is 100%, so each parameter already has a detailed description. The tool description merely enumerates the filter names and restates the offset/limit caps already present in the schema, adding no new meaning or operator examples beyond that.

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 ('Read visible Redmine issues from GET /issues.json') and clearly scopes it to the configured API user. The extensive list of filters differentiates it from sibling single-issue and resource-specific tools like get_issue and list_my_assigned_issues.

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 usage for listing issues with arbitrary filters but does not explicitly say when to choose this tool versus alternatives such as list_my_assigned_issues or get_issue. It provides clear context on capabilities but no exclusions or alternative routing.

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

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

Annotations already mark the tool read-only and idempotent. The description goes well beyond them by disclosing the field-name mapping to camelCase, null/omitted description handling, lack of browser links, and possible HTTP 401/403/404 responses without an exposed body.

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 dense but every sentence carries unique information: endpoint, scope, lack of controls, field mapping, auth/browser-link caveats, error behavior, and non-mutating guarantee. Nothing is wasted or redundant with the annotations.

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

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

For a zero-parameter read tool, the description covers endpoint, auth expectations, response mapping, error behavior, and safety. An output schema exists for return values, so the description is fully 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?

There are zero parameters, and the schema already reflects this. The description adds meaningful value by explicitly stating that the endpoint accepts no query, include, or pagination controls, removing any doubt about hidden options.

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, and endpoint: 'Read all Redmine issue statuses from GET /issue_statuses.json.' The scope ('all') and resource are unambiguous, and the resource is distinct from every 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?

Provides clear context: this is a complete read with no query/include/pagination controls and uses ordinary authentication. It does not name alternative tools, but no sibling covers issue statuses, so the omission is acceptable.

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, and openWorldHint=true. The description adds the authentication context and ordering, which are useful behavioral traits not covered by annotations. However, it doesn't disclose pagination defaults or that it only returns issues visible to the token user (e.g., permissions limitations), so it doesn't go far beyond annotations.

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

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

The description is two sentences with no waste. The primary purpose and scope are front-loaded, and it's appropriately sized for a 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?

Given the simplicity, 3 params (all optional with defaults), rich annotations, and presence of an output schema, the description is nearly complete. It might benefit from noting that results are limited to issues visible to the token's user (permissions), but the tool name already implies this. Minor gap, so 4.

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 (limit, offset, status) with descriptions, defaults, and constraints. The description adds no information about these parameters, but the baseline is 3 because the schema does the heavy lifting. No need for extra parameter explanation.

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'), resource ('Redmine issues assigned to the user...'), and the authentication context ('represented by the server's configured API token'), clearly distinguishing it from general list_issues. It is specific 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?

The description clearly specifies the scope (only issues assigned to the token user) and ordering (most recently updated). It implies that this is the tool to use for personal assigned issues, but it does not explicitly contrast with list_issues or mention when not to use it. Given the naming and sibling context, the guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'never changes Redmine data' is redundant. It adds value by specifying visibility rules, the configured API user scope, and pagination behavior beyond what the schema provides. 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?

Two sentences, front-loaded with the core action, no wasted words. Efficient and to the point.

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?

Low-complexity tool with full schema coverage and annotations covering safety. Output schema exists. The description covers scope, pagination, visibility rules, and read-only behavior. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so each parameter is fully described in the schema. The description only mentions pagination controls generically without adding syntax or format details beyond the schema. 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?

States a specific verb (read) and resource (global Redmine news) with the endpoint, and implicitly distinguishes from the sibling list_project_news by saying 'global'. The tool's scope is 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?

Clearly implies use for site-wide news rather than project-specific news, and notes it never changes data, reinforcing read-only usage. However, it does not explicitly name the alternative tool (list_project_news) or provide explicit when-not guidance, leaving some inference to the agent.

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=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat safety. It adds valuable context: the tool never downloads files, changes data, and describes auth failures (401/403/404) and response sanitization. However, it doesn't describe the output schema details (though an output schema exists) and the allowance of fields, but that's beyond annotations. It adds significant behavioral context beyond the hints, but could include more about rate limits or response size (minor).

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 dense paragraph that's front-loaded with the core action and resource, then lists constraints and behaviors. It's efficient, with no fluff, but could be structured with bullet points for readability. The information is all relevant, and the length is justified given the complexity of the behaviors described.

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?

This is a read-only, one-parameter tool with a rich output schema. The description covers the essential call details (no query string, response ordering, sanitization, links, auth permissions, error codes, and non-destructive nature). Given the output schema exists, the description doesn't need to detail return fields. It's complete for an agent to call correctly, with no obvious missing information.

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

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

Schema coverage is 100% with a detailed description of project_id (positive numeric ID or valid identifier). The description adds the nuance that the ID must be positive numeric or valid identifier, but the schema already says that. The description doesn't add much beyond the schema, so baseline 3 is appropriate. It could clarify what 'valid project identifier' means (e.g., the pattern in schema) but that's already in 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 the specific action ('Read a project's files') and the resource (GET /projects/:project_id/files.json). It distinguishes itself from siblings by specifying it's for the configured Redmine API user and focuses on files, which is distinct from list_projects, get_issue, etc. The purpose is precise 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 provides clear context for when to use this tool: to read a project's files, and explicitly notes it doesn't support pagination, filters, or includes, guiding the agent to use plain requests. It doesn't explicitly name alternatives like 'use list_projects to find project IDs' or when not to use it, but the context is clear enough for a read tool. It lacks explicit 'when-not-to-use' but the endpoint specification 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?

Beyond the annotations, it discloses the lack of pagination/filters, response order preservation, camelCase mapping, total_count passthrough, safe URL handling, why categories/assignees get no URLs, permission requirements, and possible HTTP error codes. This is thorough and materially helps an agent anticipate 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 description is long but each sentence delivers a distinct piece of useful information: endpoint, query behavior, mapping, URL rules, authorization, errors, and side-effect guarantee. It is dense rather than padded, though slightly heavy for a single-parameter read 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?

With an output schema present and annotations covering read-only/idempotent behavior, the description adds endpoint, authorization, error handling, transformation details, and a non-mutation guarantee. Nothing needed to call the tool correctly seems 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 input schema already fully documents project_id with 100% coverage, and the description mostly restates it ('positive numeric project ID or valid Redmine project identifier'). It adds no new parameter-specific behavior, so the baseline of 3 is appropriate.

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

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: 'Read one project's issue categories from GET /projects/:project_id/issue_categories.json'. This clearly identifies the operation and distinguishes it from sibling tools like list_projects (all projects) and get_issue_category (a single category).

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 usage context: this reads categories for one project, for the configured API user, subject to the project's view_issues permission. It does not explicitly name alternatives or provide 'when not to use' guidance, but the intended scope is unmistakable.

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 beyond annotations: it is paginated, results distinguish user vs group principals, roles including inherited roles are preserved, and Redmine may return HTTP 403 based on permissions. It also explicitly states 'This tool never changes Redmine data,' reinforcing the read-only nature. This is strong added context, though it doesn't detail the output schema shape (which is covered by the output schema).

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

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

The description is a single dense paragraph that front-loads the core action and resource, then covers pagination, result contents, permissions, and safety. Every sentence adds information. It is slightly long but not bloated; the structure is logical. A 5 would require even tighter organization, but this is well above average.

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 paginated read tool with a rich output schema, the description covers the essential context: the endpoint, the required parameter, pagination behavior, result contents, permission caveats, and safety. The output schema exists, so return values need not be described. The 403 caveat and non-admin note are particularly useful for an agent deciding whether to call this tool. 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 description coverage is 100%, so the schema already documents all four parameters. The description adds meaning by explaining pagination semantics: default limit of 25, maximum limit of 100, and that page is converted to an offset using the selected limit. It also clarifies that project_id can be a numeric ID or a valid project identifier. This goes beyond the schema's field-level descriptions, 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 ('Read'), a specific resource ('paginated memberships from GET /projects/:project_id/memberships.json'), and the API context. It distinguishes itself from the sibling get_project_membership by focusing on the paginated list, and it names the configured Redmine API user as the actor. This is unambiguous and clearly 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?

The description gives clear context: it is a non-admin read, uses Redmine's pagination rules, and requires a project_id. It does not explicitly name an alternative tool for single-membership retrieval, but the sibling list get_project_membership is implicitly the alternative. It also notes that Redmine enforces project visibility and may return 403, which helps an agent decide when to use it. Missing an explicit 'use get_project_membership for a single membership' statement, so not 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context: it never changes Redmine data, it respects Redmine's visibility rules, and it operates as the configured API user. This goes beyond the annotations without contradicting them.

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

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

Three sentences with no filler. The core action and endpoint are front-loaded, followed by the parameter requirement, pagination support, and a clear read-only guarantee. 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?

The tool is a simple read-only list operation with a rich schema and output schema, so the description covers the essentials: endpoint, required parameter, pagination, and safety. It does not describe the response shape, but the output schema exists and the annotations carry the safety profile, so 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 description coverage is 100%, so the schema already documents all four parameters. The description adds the endpoint context and confirms project_id accepts a numeric ID or identifier, but it does not add meaning beyond the schema's own descriptions. 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 states a specific verb ('Read'), a specific resource ('visible news for one Redmine project'), and the exact API endpoint. It also distinguishes itself from the sibling list_news by scoping to a single project, 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 clearly states the tool reads news for one project and mentions the required project_id, which implies when to use it. It does not explicitly name alternatives or exclusions, but the single-project scope and the sibling list_news provide enough context for selection.

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; the description reinforces this with 'This tool never changes Redmine data.' It also adds useful behavioral context beyond annotations: only projects visible to the configured API user are returned, and pagination plus association inclusion are supported.

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 with the core action front-loaded, followed by pagination and association capabilities, then a safety guarantee. Every sentence serves a purpose, though the explicit endpoint string and the word 'documented' add minor redundancy.

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

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

With an output schema present and rich annotations, the description covers the essential invocation context: resource scope, visibility, pagination controls, associations, and read-only behavior. Nothing critical is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters. The description adds context that offset, limit, and page are pagination controls and that the include parameter supports the five listed associations, but this largely restates what the schema already provides. No critical parameter meaning is missing.

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

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

The description uses a specific verb ('Read') and names the exact resource ('projects visible to the configured Redmine API user from GET /projects.json'). It clearly distinguishes this list operation from sibling getter tools like get_project by its scope (multiple projects) and the mention of pagination and associations.

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 for what the tool does, but it does not explicitly state when to use it over alternatives such as get_project or list_project_issue_categories. There is no when-not-to-use guidance, though the 'never changes Redmine data' statement implicitly rules out write purposes.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness, and the description reinforces this with 'This tool never changes Redmine data.' Beyond the annotations, it discloses meaningful behavioral traits: no pagination, no filters, no documented include controls, and Redmine preserves response order. This adds route-specific expectations that structured hints cannot convey.

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

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

The description is only four sentences and front-loads the core action and endpoint first. Every sentence adds value: the parameter format sentence is somewhat redundant with the schema, but the no-pagination/order-preservation and read-only assurances are highly relevant. It is tight without being terse, though slightly more concise phrasing of the parameter sentence would push it to 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?

For a simple one-parameter, single-output tool with an output schema present, the description is fully complete. It covers the purpose, endpoint, parameter requirements, route limitations, response ordering, and non-mutating behavior. Nothing an agent needs to invoke this correctly is missing, and the presence of a sibling get_version is implicitly distinguishable via the list-vs-single semantics.

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 parameter sentence, 'The required project_id is a positive numeric project ID or valid Redmine project identifier,' largely restates the schema property description without adding new semantics. It does not clarify behavior like validation errors, resolution order, or how identifier strings are treated, but the schema already documents the valid formats.

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 starts with a precise verb and resource: 'Read the visible/shared versions from GET /projects/:project_id/versions.json'. It names the exact endpoint and scopes the operation to a specific project, making the tool's function unmistakable. The phrase 'visible/shared versions' adds semantic nuance that differentiates this listing from a raw dump, and the singular sibling get_version is clearly a different operation.

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 clear context that this is a read-only list operation for a given project, and the 'for the configured Redmine API user' clarifies visibility scope. However, it does not explicitly say when to prefer this tool over alternatives like get_version or list_projects, nor does it state exclusions. The usage guidance is implied by the endpoint and verb rather than stated.

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

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

The description goes well beyond the annotations by disclosing ordering behavior (title-and-parent order), inclusion of safe browser links, reliance on the view_wiki_pages permission, and potential HTTP 401/403/404 errors. It also explicitly confirms non-mutating behavior, giving the agent a thorough understanding of side effects and failure modes.

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

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

The description is well organized and information-dense, front-loading the purpose, then covering route characteristics, permissions, and non-mutation. It is slightly long but every sentence contributes value, and the structure is logical.

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

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

For a single-parameter read-only tool with an output schema, the description is remarkably complete. It covers purpose, route limitations, output field specifics, permission requirements, expected HTTP errors, and explicitly confirms no data mutation, giving an agent all necessary context to invoke the tool 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 schema already documents the project_id parameter with a clear description and 100% coverage. The description repeats this information without adding new meaning, meeting the baseline expected when the schema handles parameter semantics.

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

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

The description clearly states the verb 'read' and the specific resource 'wiki page index' from an explicit API endpoint, distinguishing it from sibling tools that fetch individual pages or versions. It unambiguously communicates what the tool returns.

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 clear context about the tool's scope (no pagination, no filters, limited fields) and its read-only nature, informing when it is appropriate to use. However, it does not explicitly name alternative tools or state exclusion conditions, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral specifics: endpoint semantics, configured-user scoping, pagination defaults and caps, ordering by query name, visibility rules, and an explicit 'never changes Redmine data' statement. This goes well beyond what annotations provide.

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

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

The description is three compact sentences with the primary action front-loaded, followed by useful pagination/ordering behavior and then exclusions. Every sentence adds relevant information with no redundancy or 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?

Given the output schema exists and annotations cover safety, the description fully covers the invocation context: endpoint, user scope, pagination behavior, ordering, visibility, and unsupported filters. An agent has enough information to call the tool correctly without surprises.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates pagination controls, defaults, and caps, but adds no new per-parameter semantics beyond the schema. The 'orders by query name' detail is a collection behavior, not an additional parameter explanation.

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 specific verbs ('Read', 'List') and identifies the exact resource ('saved issue queries') and endpoint ('GET /queries.json'). It clearly distinguishes from sibling tools like list_issues or list_my_assigned_issues by clarifying that these are saved queries, not issues.

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 usage context by naming the resource and listing exclusions ('does not expose project, resource-type, or include filters'), but it does not explicitly mention alternatives or state when to prefer sibling tools. This is implied usage rather than explicit when-to-use/when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint, lowering the bar, yet the description adds substantial context beyond them: the absence of query/include/pagination controls, preservation of Redmine's position order, the id-and-name-only response shape, API-vs-HTML auth asymmetry, and the specific 401/403/404 error behavior with no upstream body exposed. This is exactly the kind of behavioral disclosure that prevents agent confusion.

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 sentence one, and nearly every sentence carries behavioral value. It is slightly longer than necessary: the note about the HTML roles page being restricted for non-admins only explains the marginal fact that results have no browser links, and the final 'never changes Redmine data' sentence mostly restates readOnlyHint. Overall efficient but not maximally lean.

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 an output schema and four safety annotations, the description covers everything needed to invoke it correctly: purpose, endpoint, response scope, ordering, auth requirements, and error behavior. Nothing material is missing for the agent to call this tool successfully.

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?

With 0 parameters, the baseline is 4. The description earns it by explicitly warning that the endpoint 'accepts no query, include, or pagination controls,' which stops an agent from attempting unsupported filters — a real semantic addition given the empty schema offers no such guidance.

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

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

The first sentence states a specific verb ('Read'), a precise resource ('Redmine's non-built-in project-member roles'), and the exact endpoint (GET /roles.json). The scope qualifier 'non-built-in' and the clarification that the list carries only id and name differentiate it from the sibling get_role, which covers the role-detail response.

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 clear context: it explicitly notes the list 'does not expose permissions, visibility settings, or other fields from the separate role-detail response,' which implicitly routes an agent needing detail to the get_role sibling. However, it never names the alternative tool explicitly or states a when-to-use/when-not-to-use rule, so it falls short of the top tier.

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 context beyond those annotations by noting that Redmine enforces the configured API user's view-time-entry permissions and visibility, and by explicitly stating the tool never changes Redmine data. This is relevant behavioral context for the agent.

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

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

The description is four sentences, front-loaded with the tool's purpose and endpoint, followed by capability, permission context, and a safety note. Every sentence contributes new, non-redundant information and the length is proportionate to the tool's complexity.

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

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

Given the rich input schema, output schema, and annotations, the description is complete enough. It covers the endpoint, filtering capabilities, pagination, permission-dependent visibility, and non-mutating behavior. No essential context 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 coverage is 100%, so the baseline is 3. The description adds value by summarizing parameter groups and emphasizing distinctions such as 'exact Redmine spent_on date/range forms' versus 'real YYYY-MM-DD from/to filters,' which helps the agent understand the differing parameter semantics without opening every schema definition.

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: 'Read visible Redmine time entries from GET /time_entries.json for the configured API user.' It clearly identifies the operation as a read/list action and is distinguishable from siblings like get_time_entry and list_time_entry_activities by the endpoint and resource 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?

The description gives clear context that this is the list endpoint for time entries and enumerates the available filters, so an agent can infer when to use it. It does not explicitly exclude alternatives such as get_time_entry for single entries or list_time_entry_activities for activities, but the context is not misleading.

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

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

Annotations already declare readonly, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: no query/include/pagination controls, preserved ordering, field-name mapping, version-dependent field availability, lack of project-specific overrides, absence of browser links, and explicit HTTP error behavior. This is rich behavioral disclosure that helps the agent anticipate edge cases.

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 core purpose, followed by logically grouped behavioral details, version caveats, and error behavior. It is longer than strictly necessary, and some statements like 'This tool never changes Redmine data' partly duplicate annotations, but for a tool with Redmine-specific quirks the detail is mostly earned.

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 endpoint, field mapping, ordering, null handling, version support, scope limitations, error behavior, and safety profile. With an output schema already available, the description leaves no important gap for an agent deciding whether and how to call this 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?

The tool has zero parameters, so there is no parameter burden to carry. The description still clarifies that the endpoint 'accepts no query, include, or pagination controls', which prevents the agent from inventing unsupported arguments. This is appropriate for a no-parameter 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: 'Read all shared Redmine time-entry activities from GET /enumerations/time_entry_activities.json'. It clearly distinguishes this tool from sibling list tools by naming the exact endpoint, the global scope, and by noting that project-specific overrides are not returned.

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 about what the endpoint returns and explicitly states that project-specific activity overrides are not included, which is a useful exclusion. However, it never names an alternative tool or says when to use this one versus a sibling like list_time_entries or list_issue_statuses, so the usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: no pagination controls, field name mapping (id→id, name→name, etc.), version-dependent availability of description and enabledStandardFields, absence of browser links due to no show route, and error behavior (HTTP 401/403/404 without upstream body). It also explicitly states 'This tool never changes Redmine data,' reinforcing the read-only nature beyond the annotations.

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

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

The description is dense but every sentence adds information: endpoint, auth, lack of controls, field mapping, version notes, link absence, error behavior, and safety guarantee. It is front-loaded with the core action and endpoint. Slightly long but justified given the version-dependent field details and error behavior; 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?

The tool has zero parameters, an output schema exists, and annotations cover safety. The description covers endpoint, auth, field mapping, version caveats, error behavior, and the absence of pagination/links. For a simple list tool, nothing an agent needs to call it correctly is missing. The output schema handles return values, so the description needn't repeat them.

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 the schema is empty with 100% coverage. The description explains that there are no query, include, or pagination controls, which is meaningful context for an agent that might otherwise expect parameters. Since there are no parameters to document, the description's clarification that no controls exist is valuable and earns above the baseline.

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

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

The description clearly states the tool reads all Redmine trackers from a specific endpoint (GET /trackers.json) for the configured API user. It distinguishes itself from sibling tools by naming the resource (trackers) and the read-only nature, and the title reinforces the resource. The verb 'Read' is specific and the scope is 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?

The description explains that this endpoint accepts ordinary API authentication and has no query/include/pagination controls, which tells the agent when this tool is appropriate (simple list retrieval) and that no filtering is possible. It doesn't explicitly name alternatives, but the sibling list (e.g., list_projects, list_issue_statuses) makes the resource-specific usage clear. It also notes the HTML index is admin-or-API-only, implying this API path is the accessible route.

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 signal read-only, open-world, idempotent, non-destructive behavior, and the description adds meaningful detail: Redmine's 25-result default, 100 limit, upstream ordering, exposed fields, omission of unsafe URLs, and the guarantee that the read never mutates data. This goes well 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 dense but efficient; each sentence earns its place. It front-loads the core purpose and endpoint, then adds restrictions, defaults, and result behavior without filler or repetition beyond what is necessary.

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 15-parameter search tool with no required parameters, the description covers endpoint, scope, supported/rejected controls, pagination defaults, result shape, and safety. The rich output schema and detailed input schema carry the remaining burden, so 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 coverage is 100%, so the baseline is 3. The description adds value by explaining how 'query' maps to Redmine's q parameter, grouping supported controls, explicitly listing rejected parameters, and documenting defaults/caps that are not fully captured in individual schema descriptions.

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 verb ('Search'), resource ('visible global Redmine content'), and endpoint (GET /search.json). It clearly distinguishes this tool from the sibling listing tools by emphasizing global content search and explicit scope restrictions.

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 clear context for when to use this tool: searching visible global Redmine content. It also states which Redmine controls are rejected (project_id, page, include, internal/admin-only), giving useful boundaries, though it does not explicitly name alternative sibling tools.

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