jira-delivery-mcp

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds the non-obvious behavioral trait that the returned content is cleaned and truncated to a size bound rather than returned raw. It does not mention authentication requirements or what happens at truncation, so it stops short of full 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?

A single sentence with no filler, front-loading the verb, resource, and retrieval key before the output characteristic. Nothing could be removed without losing information.

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 both parameters fully documented, the description only needs to convey the operation and its output nature, which it does. The remaining ambiguity is what 'cleaned' means (format, loss of macros/images) and error behavior, which are minor for a simple read 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 both pageId and maxChars are already documented in the schema. The description reinforces the ID-based lookup and the size-bounding concept but adds no format or syntax detail beyond structured fields; baseline 3 applies.

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 specific resource (a Confluence page), and the selection key (by ID), plus what it returns (a cleaned, size-bounded summary). This cleanly separates it from confluence_search, which locates pages rather than fetching one by identifier.

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 phrase 'by ID' implies the precondition for use, but there is no explicit when-to-use guidance, no statement of when to prefer confluence_search, and no note about behavior on missing or inaccessible pages. Usage is inferable but not spelled out.

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 and openWorldHint, so safety is covered. The description adds one genuine behavioral trait beyond that — results are 'ranked by relevance and authority' — but says nothing about empty-result behavior, ranking inputs, or how open-world space discovery interacts with the configured space default.

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?

One sentence, front-loaded with the action and resource, and the parenthetical examples earn their place by narrowing scope. Nothing redundant or restated from the 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 and annotations cover the safety profile, so the description does not need to explain return values. Given four fully documented parameters, the definition is sufficient to invoke correctly; only the selection guidance against siblings is thin.

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 issueKey, spaceKeys, maxResults, and includeLowRelevance are all documented in the schema. The description contributes no additional parameter meaning, which is the correct baseline of 3 when the schema carries the full burden.

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 ('Find Confluence pages') anchored to an input ('relevant to a Jira issue') and gives content-type examples (specs, designs, runbooks) that scope what counts as relevant. An agent can separate it from confluence_get_page (single-page fetch) by inference, though no sibling is named explicitly.

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?

Usage is implied: call it when you hold a Jira issue and want supporting documentation. There is no explicit when-not guidance and no routing to unhinted alternatives such as confluence_get_page for full page bodies or jira_prepare_work_brief for briefing workflows.

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 declare readOnlyHint and openWorldHint, and the description adds substantial context beyond them: checks run independently, the issue is fetched automatically, and the possible verdict values (ready_for_pr, needs_work, insufficient_evidence, not_applicable) plus per-criterion coverage are disclosed. That is exactly the behavioral detail an agent needs.

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 and the pre-PR warning are front-loaded, and the verdict-value preview is placed at the end where it belongs. Density is high but nearly every clause carries new information; the wording is slightly compressed with semicolons and dashes.

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 values need not be described, yet the verdict summary still helps set expectations. Combined with the check semantics, the PR/planning timing guidance, and the auto-fetch note, nothing an agent needs to call this 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?

Schema coverage is 100% so the baseline is 3, but the description goes further by explaining what the alignment, dod, and impact checks semantically do and when to select the impact-only subset. It doesn't clarify baseBranch/compareRef/maxDiffChars, which the schema already handles.

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 (check local diff work against a Jira issue) and immediately names the three sub-checks (alignment, dod, impact) plus what each evaluates. An agent can distinguish this from siblings like delivery_traceability_matrix or jira_get_issue without opening the 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?

Gives explicit timing guidance: run alignment/dod before opening a PR, and use checks ["impact"] when planning before code is written. Strong conditional routing, though it names no sibling alternative or when-not-to-use case for the tool as a whole.

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 only declare readOnlyHint and openWorldHint; the description adds the meaningful operational facts that it fetches the Jira issue itself, returns Markdown, and writes no files. It does not disclose cost/latency of assembling a report or any auth prerequisite, but the key behavioral profile is covered.

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 tight sentences: artifact list first, selection guidance second, operational facts (fetch behavior, Markdown return, no file writes) last. No filler, and the 'no files written' constraint is placed where an agent will see it.

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 explanation, and the description covers inputs' coupling and side effects. It leaves gaps around how much of the repo/diff is scanned and whether remote Jira/Confluence calls have limits, but nothing blocks 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 description coverage is 80%, so the baseline is 3. The description's notes on persona and audience restate what the schema already says ('Required when type is reviewer_report', 'release_notes only'), adding no syntax or conditional rules beyond the structured fields; includePrDiff's coupling to test_strategy is only hinted 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?

Names a specific verb and resource ('Generate a delivery artifact from a Jira issue and the local diff') and enumerates all five artifact types with their distinguishing traits. An agent can distinguish this from delivery_check_changes or delivery_generate_agent_pack without opening the 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?

Gives explicit selection guidance for two of the five types ('Use test_strategy to plan tests and reviewer_report to review a ticket from a persona's point of view') and flags the conditional requirements (persona for reviewer_report, audience for release_notes). It does not say when to prefer this over sibling tools like delivery_generate_agent_pack or how qa_handoff/release_notes/task_report differ in situation.

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 destructive=true and idempotent=true, so the safety profile is covered. The description adds genuinely useful context by mapping each client enum to its on-disk directory, but it never warns that existing files can be replaced or clarifies how destructive behavior interacts with `overwrite`.

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?

A single sentence with the action front-loaded and the client-to-path mapping in a compact parenthetical. The parenthetical is dense but each clause carries real information, 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?

An output schema exists, so return values need no explanation, and the three parameters are largely covered by schema plus the description's path mapping. For a small write tool with strong annotations, an agent has enough to invoke 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 67% and documents `repoPath` and `overwrite`. The description goes further than the schema by spelling out the filesystem destination for every `client` value, which the bare enum does not convey. It still says nothing about what the generated pack contains, but that is outside parameter scope.

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 ('Write reusable Jira delivery prompts/commands ... into the repository') plus the concrete target directories per client. An agent can tell it produces files, but nothing distinguishes it from the sibling `delivery_generate`, which sounds closely related.

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?

No when-to-use statement, no prerequisites (e.g. must a work brief exist first?), and no mention of the sibling `delivery_generate` as the alternative. The agent must infer timing from the tool name alone.

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 flag destructiveHint=true and non-readOnly, and the description is consistent, clarifying that 'clear' is what deletes the stored patterns. It adds a prerequisite the schema cannot express: storing requires DELIVERY_PATTERN_MEMORY_ENABLED=true in the server environment, which is high-value operational context. What's missing is where patterns live (per-repo vs global) or whether a scan overwrites existing entries.

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 tight sentences, front-loaded with the core capability, then the action breakdown, then the environment prerequisite. No filler or 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?

With an output schema present, return values need no explanation, and the env-var prerequisite plus action semantics cover the main gaps. For a tool that mutates stored state, a note on persistence scope and overwrite behavior would complete it.

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 50%, with repoPath documented as 'Repository to inspect'. The description compensates for the bare enum by defining what each action does, which the enum values alone do not convey. It does not note repoPath's default of '.' or that it is ignored for get/clear.

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: 'Detect the repository's conventions (framework, test layout, tooling) and store them', plus the subordinate read/delete actions. It is distinguishable from siblings like delivery_generate or delivery_check_changes, though it never explicitly names when to prefer this over them.

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 maps each of the three actions to a concrete effect ('scan = detect and store, get = read stored patterns, clear = delete them'), which is genuine when-to-use guidance for the enum. It stops short of saying when a whole scan is warranted versus falling back to another delivery tool.

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 and openWorldHint, so safety is covered. The description adds genuinely new behavioral context: it performs its own issue fetch (explaining the open-world hint) and produces gap flags rather than a pass/fail verdict. It doesn't mention that the default includeConfluence=true triggers a second external system, which would have been a useful 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?

Two sentences plus a short routing sentence, with the core purpose front-loaded and zero filler. Each clause carries distinct information: what is built, what it maps, that it self-fetches, and which sibling to use instead.

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 (return values needn't be explained) and annotations cover the safety profile, so the burden is light. The description covers purpose, the self-fetch behavior, and sibling routing; the only missing piece is that Confluence is queried by default, which affects latency and scope for an open-world 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%, so all six parameters including baseBranch/compareRef/includePrDiff/includeConfluence are already documented. The description only reinforces that the diff comparison and requirement set are the core inputs; it adds no syntax, defaults, or interaction details beyond the schema, so baseline 3 applies.

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 artifact ("Build a requirements traceability matrix") plus the exact operation: map each requirement and acceptance criterion of a Jira issue to changed files and flag gaps. It also names a sibling (delivery_check_changes) and contrasts its output, so an agent can distinguish the two without opening either 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?

Explicitly routes the agent: use delivery_check_changes for a ready-for-PR verdict, this one for a gap-flagged matrix. It also clarifies an important prerequisite is handled internally ("Fetches the issue itself"), so the caller doesn't need jira_get_issue first. No explicit when-not conditions beyond that single alternative, 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 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real value by disclosing what the response contains and that it performs a readiness assessment. It leaves out things like how long deep/cross-space fetches take or whether the brief is cached, so it is informative but not exhaustive.

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?

Front-loaded with the core transformation, then usage, then a short disambiguator. Two dense sentences and one fragment; the parenthetical list of readiness checks is slightly crowded but every clause carries information.

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 values need no explanation here. The description covers purpose, output composition, triggering scenarios and scope of fetching, which is everything an agent needs before calling a read-only 4-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 description coverage is 100% and depth/includeConfluence/allowElicitation are each documented in the schema, so the parameter burden is already met. The prose adds no syntax or format detail beyond the schema, which is the expected baseline-3 case.

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 concrete transformation (Jira issue → ready-to-implement brief) and enumerates the output artifacts: goal, acceptance criteria, constraints, implementation prompt. 'Fetches the issue itself' distinguishes it from the sibling jira_get_issue, so an agent can pick between them without opening 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?

Gives two explicit triggering situations: starting work on a ticket, and checking readiness (blockers, missing acceptance criteria). It does not name alternatives or say when NOT to use it, e.g. 'for raw field access use jira_get_issue' — that boundary is only hinted at by the closing sentence.

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 and openWorldHint, so the safety profile is covered. The description adds real behavior beyond that: jql is constrained by projectKey and by the strict allowlist, and pagination is disclosed via data.nextPageToken with the pass-back instruction.

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?

Front-loaded with purpose, then alternatives, then pagination — a sensible ordering with no filler. It is dense but every sentence carries information; the embedded JQL example is the only element that inflates length, and it 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?

An output schema exists, so return values need not be described, yet the description still covers the one output detail that matters for correct invocation (nextPageToken). Combined with the allowlist caveat, an agent has enough to call this correctly; only the terse default-query behavior under projectKey scoping is left implicit.

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 is 3, but the description adds semantics the schema does not: jql silently gets scoped to projectKey when supplied and further narrowed under the strict allowlist. The pageToken round-trip is also explained in context rather than just as a field name.

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?

Specific verb and resource (list open Jira issues assigned to the authenticated user), with the optional project scope stated up front. An agent can tell this apart from jira_get_issue (single issue) and the confluence/delivery siblings 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?

Explicitly frames the use case ("find what to work on next") and names the in-tool alternative for custom filtering via jql, including a concrete example. It does not explicitly say when to prefer jira_get_issue for a single known issue, so it stops short of a full when/when-not map.

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