Get a Jira issue

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds real behavioral context beyond that: what 'full' depth expands to (parent, epic, linked issues, subtasks, comments) and the non-obvious side effect that includeConfluence implies full depth, which an agent could not infer. It omits cost/latency implications of full+Confluence, so it stops short of 5.

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, front-loaded with the primary capability and payload, then parameter guidance, then routing to alternatives. No filler or restatement of the name/title.

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?

An output schema exists, so return-format explanation is unnecessary. With three documented parameters and read-only annotations already in structured fields, the description covers everything an agent needs to choose this tool and 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 coverage is 100%, so baseline would be 3. The description adds genuine semantics on top: it frames why you would raise depth to 'full' (parent/epic/linked-issue context) and what includeConfluence is for (related documentation), including the implicit depth escalation the schema only hints at.

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

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

States a specific verb and resource plus the exact payload shape: 'Fetch a Jira issue as a developer brief: description, acceptance criteria, comments and attachments.' It also names the sibling it is not (jira_prepare_work_brief, delivery_*) so an agent can distinguish read-from-ticket vs. workflow-action tools without opening a schema.

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

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

Provides both the when ('Use this to read a ticket') and the when-not with named alternatives ('To start work, check readiness, verify changes or write a report, call jira_prepare_work_brief or the delivery_* tool directly'). It even explains why the alternative is needed there - they fetch the issue themselves - removing the temptation to chain this call first.

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