Get Project Epic Hierarchy

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

Annotations already declare readOnlyHint=true, and the description adds algorithmic details: fetches all epics, detects parent via parent field or inward issue links, groups by parent, and buckets unlinked epics. This goes beyond the annotation without contradicting it.

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

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

Four short sentences, all substantive. The main action is front-loaded, followed by mechanism, edge-case handling, and use case. No filler or repeated schema info.

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 output schema covers return structure, annotations cover safety, and the description explains grouping logic and the 'Unlinked' case. Minor gaps remain around behavior with zero epics or performance implications of max_epics, but these are non-critical for a read-only reporting 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 description coverage is 100%: both project_key and max_epics are fully described with patterns and ranges. The description adds no extra parameter meaning, so it correctly relies on 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+resource: 'Group a project's epics under their cross-project parent issues.' It clearly distinguishes this tool from siblings like jira_get_project_issues or jira_search by focusing on epic-to-parent grouping and explicitly mentions the 'Unlinked' fallback.

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 final sentence provides clear use context: 'Useful for understanding how a project's epics roll up to initiatives in another project.' It implies when to use this over simpler issue-listing tools, though it does not explicitly name alternatives or exclusions.

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