list_epics

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

Annotations already indicate read-only and non-destructive. Description adds project scoping and domain definition but does not disclose pagination behavior or return format. No 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?

Two sentences, front-loaded with the action and resource, followed by one clarifying definition. No wasted words.

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?

Simple list tool with good annotations, but pagination params cursor/per_page are not explained in the description. No output schema means return format is unspecified. Description is adequate but leaves 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 has 0% description coverage and description does not explain cursor/per_page semantics. 'project' implies project_id requirement, but cursor and per_page are left undocumented. Fails to compensate for low schema coverage.

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 'List all epics in a project' with a specific verb and resource. Defines epics to disambiguate from other list_* tools. Clearly distinguishes from list_work_items and 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?

Implies use when needing all epics within a given project. Does not explicitly mention alternatives or exclusions, such as retrieve_epic for a single epic or list_work_items for work items. Thus only implied usage guidance.

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