list_issues

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It reveals the 100-item cap, query_id overriding other filters, date inclusivity semantics, partial-match behavior, special status values, and the return of the total matching issue count to tell if pagination is needed. There is no annotation contradiction.

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

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

The description is long because there are 17 parameters, but it is well-structured with a one-line purpose followed by an Args list and a Returns note. Every sentence adds semantic value and there is no fluff or repetition, making it 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 high parameter count, lack of annotations, and existence of an output schema, the description is remarkably complete. It covers all parameter semantics, API limitations, filter interactions, pagination behavior, and return count information, giving an agent everything needed to select and 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?

Schema description coverage is 0%, so the description's Args section is the only source of parameter meaning. Every one of the 17 parameters is defined with syntax and examples, including custom_fields map format, sort_by field/direction examples, and the meaning of empty project_identifier and status '*'.

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

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

The opening sentence states a specific verb and resource ('List Redmine issues'), and the description enumerates all filtering dimensions (project, status, tracker, category, version, assignee, author, parent issue, subject, dates, custom fields, sorting, query, pagination). This clearly distinguishes it from sibling issue tools like get_issue, create_issue, and bulk_update_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 gives clear context on how to use filters, including notes that Redmine caps limit at 100, query_id causes other filters to be ignored, and offset+limit enable pagination. It also references list_trackers, list_project_categories, list_project_versions, and list_saved_queries for filling filter parameters. However, it does not explicitly state when to prefer this tool over alternatives like get_issue or bulk_update_issues.

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