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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior, so the safety profile is covered elsewhere. The description adds nothing beyond that: it doesn't say that editing replaces the existing comment body, what permissions are required, or that body is converted to ADF (the schema covers the ADF detail).

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 front-loaded sentence with no waste, but it is under-specified rather than genuinely concise. Being short here costs information rather than saving 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?

For a mutating tool with no output schema, 5 parameters and only 60% schema coverage, the description should carry more: which mode is triggered by commentId, edit-replaces-body semantics, and visibility restrictions. None of that is present.

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 only 60%, and the description contributes zero parameter information. The critical selector between the two modes (commentId) and the undocumented issueIdOrKey and visibilityType params are left entirely to the schema, so the description fails to compensate for the coverage gap.

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 names a specific verb (add/edit) and resource (Jira issue comment), and it signals the dual mode of operation. It stops short of differentiating itself from siblings like listJiraIssueComments or addOrEditJiraIssueWorklog, so an agent gets the what but not the how-it-differs.

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?

'or edit an existing one' loosely implies a second mode exists, but there is no guidance on when to use this versus listJiraIssueComments, addOrEditJiraIssueWorklog, or how the edit path is triggered. No prerequisites, no alternatives, no when-not.

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=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the mutation profile is covered. The description adds almost nothing beyond the name: it does not explain that a new worklog is created when worklogId is absent, how estimates are adjusted, or what side effects occur on the issue's remaining estimate.

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 eleven-word sentence with the action front-loaded and no filler. It is not padded, though the brevity is partly the cause of the coverage gaps rather than pure efficiency.

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?

For a 9-parameter, non-idempotent write tool with no output schema and roughly half the parameters undocumented anywhere, one sentence is not enough. An agent cannot tell how the estimate-adjustment parameters interact or which fields are required for each mode.

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 only 44% across 9 parameters, so the description is expected to compensate for undocumented fields such as reduceBy, newEstimate, adjustEstimate, timeSpentSeconds and issueIdOrKey. It mentions none of them, adding no meaning beyond the four parameters the schema already describes.

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 names a specific action pair (log time / edit worklog) on a specific resource (a work item's worklog), and the create-vs-edit duality matches the tool name. It does not distinguish itself explicitly from the sibling listJiraIssueWorklogs, which an agent must infer from the verb.

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?

It implies two usage modes — logging new time versus editing an existing worklog — but never states that editing requires an existing worklog identifier, nor names an alternative tool or a when-not-to-use condition. Adequate but relying on inference.

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=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result is company-managed and must derive from an existing filter, but says nothing about required permissions, failure modes, or whether a duplicate name is rejected.

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 front-loaded sentence with no filler. Every clause adds meaning (company-managed, board type, source filter) and nothing is wasted.

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 no output schema and only 25% parameter coverage, the description is thin for a creation tool. It conveys the core operation and one prerequisite, but an agent still lacks guidance on the 'name' and 'projectKeyOrId' semantics and on what is returned.

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 only 25%, so the description must compensate. It clarifies the enum values for 'type' (scrum/kanban) and that 'filterId' references an existing filter, but 'name' has no description and 'projectKeyOrId' is only covered by the schema. It partially compensates but leaves gaps.

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 states a specific verb (Create), resource (board), and scope (company-managed, scrum or kanban, from an existing filter), which distinguishes it from siblings like listJiraBoards and getJiraBoardConfig. It is clear but does not explicitly name an alternative or boundary against siblings, so it stops short of a 5.

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 'from an existing filter' implies a prerequisite, but the description never says when to use this tool versus creating a board another way or checking for existing boards first. No alternatives or exclusions are given, leaving usage largely to inference.

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 non-read-only, non-idempotent, open-world, non-destructive, so the safety profile is covered by structured data. The description adds nothing beyond that: no note on required auth scopes, that retries will duplicate issues, or that nested custom fields are passed through opaquely.

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 front-loaded sentence with zero waste, but it is under-specified rather than genuinely concise — the brevity comes at the cost of any useful context.

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?

This is a mutation tool with nested object parameters and no output schema, so the description carries real burden. It omits prerequisites, the fields/update override mechanics, and what a successful create returns (e.g. the new issue key), leaving the agent to infer all of 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 description coverage is 71% (below the 80% baseline), so the description must compensate for the gaps, and it doesn't. Notably the 'update' parameter has no description in either the schema or the description, and the relationship between issueTypeId and issueTypeName is only implied by the schema text.

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 clear verb+resource ('Create a new Jira work item'), which tells an agent exactly what the tool does. It does not, however, distinguish itself from siblings like editJiraIssue or createJiraIssueLink, and the vaguer term 'work item' rather than 'issue' is a small miss.

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 guidance, no prerequisites (project must exist, issue type must be valid, required permissions), and no mention of the alternative approach via issueTypeId vs issueTypeName. The agent gets no routing help.

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=false, idempotentHint=false and openWorldHint=true, so the mutation profile is covered. The description adds nothing beyond that — it doesn't note that repeated calls create duplicate links, whether permissions are needed, or what the response returns. Minimal value beyond structured data.

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 front-loaded sentence with zero waste. It is efficient, though its brevity borders on under-specification rather than true conciseness.

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?

For a non-idempotent mutation tool with no output schema and two undocumented required parameters, the description should explain link directionality, the required link-type lookup step, and duplicate-link behavior. None of that is present.

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 only 50%: linkTypeName usefully points to listJiraIssueLinkTypes and comment is documented, but inwardIssueKey and outwardIssueKey have no description anywhere, and the directionality of inward/outward is exactly the semantics an agent needs. The description compensates for none of this.

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?

Clear verb+resource ("Create a link between two Jira work items") that an agent can understand immediately. It does not, however, distinguish itself from relatives like listJiraIssueRemoteIssueLinks or listJiraIssueLinkTypes, so a reader must infer the boundary themselves.

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 guidance, no prerequisites (e.g. that link types must be enumerated first), and no mention of alternatives. The agent gets no routing help from the description.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description usefully adds that the URL is 'short-lived' and that output includes a local save command, but it omits any indication that savePath writes a file to the local filesystem — a side effect worth flagging against readOnlyHint.

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 front-loaded sentence with no filler; the primary result (the URL) leads and the secondary return artifact follows.

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 no output schema, the description does carry the burden of describing returns and does so partially (URL plus command). However it leaves the savePath file-write behavior and the undocumented attachmentId unexplained, which is a meaningful gap for a two-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 coverage is only 50%: savePath is described in-schema but attachmentId has no description anywhere. The description only loosely gestures at savePath behavior ('a local command to save the file') and says nothing about what attachmentId expects, an identifier format, or where to obtain it.

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 gives a specific verb ('Get a download URL') and resource ('an attachment'), and its output-shape detail (a short-lived URL plus a local save command) separates it from the sibling uploadAttachmentToJiraIssue. It never names a sibling explicitly and omits the savePath write-to-disk behavior, so it stops short of a 5.

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?

There is no when-to-use/when-not guidance and no mention of alternatives among the many Jira siblings. It also doesn't tell the agent when to prefer the URL-only path versus supplying savePath, so the caller must infer the two usage modes.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is largely covered. The description adds the 'key/value store' framing and the entity-type scope, but says nothing about overwriting an existing property value, required permissions, or reversibility.

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 front-loaded sentence that leads with the verb and resource with no padding. The trailing enumeration of entity types is slightly redundant with the schema, and 'an work item' is a minor grammatical slip.

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?

For a 7-parameter mutation tool with no output schema, the description is thin: it does not explain the per-entity-type parameter combinations or the overwrite semantics. The schema descriptions cover most of the conditional wiring, but the description does little to compensate for the remaining 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 coverage is 71% and the schema already documents the conditional parameters (accountId for user, dashboardId for dashboardItem, issueIdOrKey for worklog, entityId otherwise). The description only restates the entity-type list that the entityType enum already carries, adding no format or conditional detail beyond the schema.

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 ('Set') and resource ('property in the key/value store') and enumerates the entity types it applies to, which is enough for an agent to recognize a write-to-property operation. It does not explicitly differentiate itself from the sibling getJiraEntityProperty (its read counterpart), so it stops short of a 5.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative. The agent is not told to prefer getJiraEntityProperty for reads or that this overwrites an existing value, so usage must be inferred entirely from the name.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and retry profile is covered elsewhere. The description adds one genuinely useful behavioral constraint — that only fields editable on that work item may be set — but says nothing about permission requirements, the effect of notifyUsers, or whether unspecified fields are left untouched.

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 front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly a symptom of missing detail rather than deliberate tightness.

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?

For a 4-parameter mutation tool with two open-ended nested objects, no output schema, and zero schema documentation, the description is far too thin. An agent cannot know what to put in fields versus update, what notifyUsers defaults to, or what a successful edit returns.

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?

With 0% schema description coverage and 4 parameters, none of the semantics are documented in the schema. The description's mention of 'fields' only loosely gestures at the fields and update objects; issueIdOrKey, notifyUsers, and especially the empty-but-open nested fields/update shapes (additionalProperties: true) get no explanation of expected contents or format.

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 (Edit) and resource (existing work item), so the core action is unambiguous. It does not differentiate itself from siblings that also mutate an issue, such as transitionJiraIssue, addOrEditJiraIssueComment, or editJiraEntityProperty, leaving the agent to infer the boundary.

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?

There is no when-to-use guidance and no mention of alternatives. Given a sibling list containing transitionJiraIssue, addOrEditJiraIssueComment, and addOrEditJiraIssueWorklog, the description never explains why an agent should route a change to editJiraIssue rather than one of those. Usage is only implied by the name.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds no further behavioral context beyond these annotations—no mention of auth requirements, rate limits, or result scoping. Since the description adds nothing beyond what structured fields provide, it falls below the midpoint.

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, front-loaded sentence with no wasted words. However, for a tool with four parameters and no output schema, it may be overly terse—the brevity is efficient but leaves structural context thin.

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 description is incomplete for a tool with four parameters (three undocumented), 25% schema coverage, and no output schema. It does not explain how projectKey and issueIdOrKey interact, what results are returned, or how to use the tool effectively. The annotations cover safety basics, but param and usage gaps remain.

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 25%—only 'query' is documented. The description does not explain projectKey, issueIdOrKey, or maxResults, leaving three of four parameters undocumented. The phrase 'space or work item' faintly hints at the purpose of projectKey/issueIdOrKey, but it is too vague to compensate for the coverage gap.

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 ('Find') and resource ('users assignable to a Jira space or work item'), distinguishing the tool from generic user lookups like getJiraUser or lookupJiraAccountId. An agent can immediately understand its scope 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?

The description only states what the tool does. It gives no explicit guidance on when to use it versus alternatives (e.g., getJiraUser for general user lookup), nor any prerequisites or exclusions. Usage is inferable from the purpose but not stated.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the content shape of the response (filter, column layout, mapped statuses), which is mildly useful, but says nothing about permissions, failures, or volatility beyond that.

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?

It is a single tight fragment with zero filler and the resource is front-loaded. The terseness is appropriate, though the same brevity leaves required detail out.

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?

For a one-parameter read tool with full annotation coverage and no output schema, the description covers what the response contains reasonably well. It still omits any indication of when to use it and what boardId refers to, leaving the definition minimally viable rather than complete.

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?

The single parameter boardId has 0% schema description coverage and is never mentioned in the description, so no meaning is added beyond its name and type. The description does not compensate for the coverage gap as required for low-coverage schemas.

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 fragment names the specific resource (a board's configuration) and enumerates what it exposes – filter, column layout, and mapped statuses – which distinguishes it from siblings like listJiraBoards and getJiraBoardIssueData. However, it is a noun phrase with no verb, so the retrieval action itself must be inferred from the tool name.

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?

There is no guidance on when to call this versus listJiraBoards or getJiraBoardIssueData, and no prerequisites or exclusions are stated. The agent must infer the use case from the 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 declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description usefully signals that the source can be board, backlog, or both, and that results can be filtered/capped, but it says nothing about pagination behavior or how defaults are applied despite startAt/maxResults existing. Some added value over annotations, but thin.

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, front-loaded sentence with no filler or repetition. It is efficiently sized, though its brevity comes partly at the cost of detail rather than from tight editing of richer content.

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?

For a 6-parameter tool with 17% schema coverage and no output schema, the description leaves significant gaps: pagination limits (startAt/maxResults defaults), the fields projection, and the required boardId are unaddressed. The read-only annotations do lower the behavioral burden, but the parameter-level information an agent needs to call this correctly is largely 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 description coverage is only 17% — just the 'source' enum has a description. The description's 'count and JQL filtering' vaguely gestures at maxResults and jql, and 'board, backlog, or both' mirrors the source enum, but boardId, startAt, maxResults semantics/defaults, and the fields projection parameter remain unexplained in both places. Compensation for the coverage gap is minimal.

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 names the resource (work items/issues) and the scope (a board, its backlog, or both), which is clearer than a bare title. However, it is a noun phrase with no verb, and it does not distinguish itself from the closely related sibling searchJiraIssuesUsingJql, which it partially overlaps with by citing 'JQL filtering'. The purpose is inferable but not crisply stated.

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?

There is no explicit when-to-use guidance and no mention of alternatives. The phrase 'with optional count and JQL filtering' lists capabilities rather than telling the agent when this tool should be chosen over searchJiraIssuesUsingJql or getJiraBoardSprintData. The agent must infer the selection criteria from the 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description's only added behavioral fact is the active-sprint default, which is genuinely useful but thin; nothing is said about return shape, pagination, or errors.

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 front-loaded sentence with a semicolon; nothing is wasted. It is efficient, though arguably too terse to carry the needed parameter and usage detail.

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?

For a 3-parameter read tool with full annotation coverage but no output schema, the description covers the happy path but omits what 'sprint data' includes and never explains includeIssues. It is minimally viable but leaves gaps an agent must fill by trial.

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 only 33%: sprintId's default is duplicated from the schema, while boardId and especially the boolean includeIssues are undocumented in both places. The description does not compensate for the includeIssues gap, leaving an agent guessing what that flag does.

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 (resolve) and resources (board + sprint data), and the phrase 'in one call' hints at the combined retrieval that distinguishes it from single-resource siblings. However, it never names which sibling to prefer (listJiraBoardSprints, getJiraBoardIssueData), so an agent still has to infer the boundary.

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 clause 'defaults to the active sprint' implies the common usage path when sprintId is omitted, but there is no explicit when-to-use/when-not guidance or alternatives named against the many board/sprint siblings. Usage is inferable but not stated.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered without the description. The description adds nothing beyond that structured data — no note on authentication scope, cached results, or what fields 'details' covers.

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 short, front-loaded sentence with no filler. It is efficient, though its brevity edges into under-specification rather than tightness.

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?

For a no-arg read tool this is close to adequate, but with no output schema the description does not indicate what 'details' includes (accountId, display name, email), which matters because lookupJiraAccountId exists as a sibling and agents often need the current user's account ID.

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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate at the parameter level.

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 resource (current Jira user) and implies a read of its details. The word 'current' distinguishes it from the sibling getJiraUser, though the description never names that sibling or explicitly contrasts the two.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as getJiraUser or lookupJiraAccountId, despite those siblings overlapping heavily with this tool's domain.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only the 'key/value store' framing and entity coverage; it says nothing about authentication needs, error behavior when a property is absent, or what value shape is returned.

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 front-loaded sentence with no wasted clauses, though it contains a small grammatical slip ('an work item') and could have used its one sentence to add usage or return-value context.

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?

There is no output schema, so the description ought to describe the returned property value, yet it does not. Combined with no usage routing and mid-level parameter coverage, the definition is adequate for a simple read but leaves the agent guessing about return shape and the entity-to-parameter mapping.

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 the schema already documents the conditional requirements for entityId, accountId, dashboardId, and issueIdOrKey. The description merely restates the entity types from the enum and adds no format or relationship detail beyond the schema.

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) and resource (property from the key/value store) and enumerates the five entity types the tool operates on, matching the entityType enum. It is clearly distinct from most siblings, though it never names editJiraEntityProperty as its write counterpart.

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 offers no when-to-use or when-not-to-use guidance and does not point to editJiraEntityProperty for modification of the same store. The entity list is scoping information, not usage guidance, leaving the agent to infer context.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that — no note on permissions/scopes, error behavior for missing keys, or response size/default field set. With no added behavioral context against complete annotations, this stays low.

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 front-loaded sentence naming verb, resource, and identifier with no filler. It is efficient, though its brevity is partly under-specification rather than disciplined concision.

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?

For a read-only getter whose annotations carry the safety profile, the essentials are present. However, with no output schema and no indication of what is returned (full issue by default, fields/expand narrowing, changelog option), an agent cannot anticipate the response shape or default payload.

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 75%; the schema documents issueIdOrKey ('PROJ-123'), expand (example values), and fields, while properties is undocumented. The description only restates 'by ID or key', which the schema already says, so it adds no meaning and does not compensate for the undocumented properties parameter.

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 (Get) and resource (Jira work item) with the identifying input (ID or key), which implicitly separates it from searchJiraIssuesUsingJql, createJiraIssue, and editJiraIssue. It does not explicitly name a sibling or clarify how it differs from the other read-family tools, so it stops short of a 5.

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?

There is no statement of when to use this tool versus alternatives: no mention that it is the direct-lookup path when you already hold a key, and no pointer to searchJiraIssuesUsingJql when you do not. Usage is only inferable from the name.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the result is field metadata used for correct work-item creation, but says nothing about response size, caching, or how missing/unknown issue types behave — modest added value given the annotation coverage.

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 efficient sentence that front-loads what is returned and appends the purpose. No filler, though it is arguably terse enough to leave gaps.

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?

There is no output schema, so the description carries some burden for explaining the return, which it does only broadly ('schema and field metadata'). For a metadata lookup feeding createJiraIssue, an agent gets the gist but not enough detail on the shape of the returned field definitions.

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% for two required parameters. 'A specific work item type in a project' loosely maps to issueTypeId and projectIdOrKey, but the description never clarifies that one may be an ID or a key, nor what format each expects, so it fails to compensate for the schema gap.

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 states a specific resource — schema and field metadata for a given work item (issue) type within a project — plus the downstream purpose of creating work items with correct fields. It is distinguishable from siblings like listJiraProjectIssueTypesMetadata, which lists types rather than the field schema for one type, though it never names that sibling 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?

The phrase 'for creating work items with correct fields' implies the usage context (a prerequisite to createJiraIssue), but there is no explicit when-to-use/when-not, no mention of needing to resolve issue type IDs first via listJiraProjectIssueTypesMetadata, and no stated prerequisites.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered structurally. The description adds no behavioral context beyond that – nothing about pagination, auth requirements, or what 'evidence' actually contains – so it earns little beyond the annotation baseline.

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 short sentence with no padding, which is appropriately front-loaded, but it is terse to the point of under-specification given the schema and behavioral gaps.

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?

For a one-parameter tool with no output schema and no parameter documentation, the description should explain what related work is, how versionId is obtained, and roughly what is returned. It does none of these, leaving the definition materially incomplete.

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?

There is one required parameter (versionId) with 0% schema description coverage, so the description carries the full burden. It only loosely hints at the target via 'space version (release)' and gives no format, source, or lookup guidance for versionId.

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 names the resource ('related work links on a space version/release') but is a bare noun phrase with no verb, and 'space version' is imprecise terminology for what the sibling tools call a project version. It does not explicitly distinguish itself from manageJiraProjectVersionRelatedWork, leaving the read-vs-write split to be inferred from the name.

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 guidance, no prerequisites, and no mention of the write-side counterpart manageJiraProjectVersionRelatedWork. The agent must infer that this is the read operation purely from the tool name.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds nothing behavioral beyond the vague list/single duality – no pagination behavior, no auth requirements, no return shape. For a paginated list endpoint this is a notable gap even with the lower annotated bar.

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?

It is a single short fragment with no bloat, so it is not verbose. However it is under-specified rather than concise – there is no front-loaded verb or resource statement, and the fragment omits essential framing.

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?

For a 4-parameter tool with no output schema and only 50% parameter coverage, the description should explain both the list and single-version modes, pagination, and the relationship between projectIdOrKey and versionId. It does none of these, leaving the agent to reconstruct behavior from parameter names.

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%: versionId and projectIdOrKey carry inline descriptions while startAt and maxResults are undocumented. The description's 'or a single version' loosely maps to versionId, but it adds no meaning beyond the schema's own text and leaves the pagination parameters unexplained. Baseline 3 when the schema does the heavy lifting.

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 is a noun fragment ('A space's releases/versions, or a single version.') with no verb, so the agent must infer that it lists versions. It gestures at the list-vs-single duality, but 'space' is Confluence terminology rather than Jira's 'project', which adds confusion. The name getJiraProjectVersions clarifies more than the description does.

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?

There is no indication of when to use this versus manageJiraProjectVersion or getJiraProjectVersionRelatedWork, both of which appear in the sibling list. No prerequisites, no conditions, no exclusions are stated. The 'or a single version' clause hints at two modes but doesn't say how to choose between them.

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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is fully covered. The description adds only the lookup-key framing ('by account ID') and says nothing about auth requirements or behavior for unknown IDs, which is minimal added value.

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 tight, front-loaded sentence with no filler. Appropriately sized for a simple read tool.

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?

A simple single-param read tool whose safety profile is covered by annotations, so little is required. The missing piece is sibling routing against getJiraCurrentUser and lookupJiraAccountId, which leaves the agent with insufficient disambiguation context.

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 0% and there is a single required parameter, so the description must carry the meaning. It does clarify that the parameter is an account ID (as opposed to email or username), which is useful given lookupJiraAccountId exists, but adds no format or validity guidance.

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 (retrieves) and resource (Jira user's profile) with the lookup key (account ID), so the agent knows exactly what it does. However, it does not distinguish itself from close siblings like getJiraCurrentUser or lookupJiraAccountId, leaving overlap unresolved.

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 guidance, no prerequisites, and no mention of alternatives. Given siblings getJiraCurrentUser (self) and lookupJiraAccountId (email-to-ID resolution) exist, the definition leaves the agent to guess which to call.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered without the description. The one bit the description adds is "visible to the current user," which signals permission-scoped results, but it says nothing about pagination behavior, result ordering, or how the open-world remote fetch behaves.

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 short, front-loaded sentence with no filler or redundancy. However, its brevity comes at the cost of substance: for a five-parameter listing tool with no schema documentation, this is under-specification rather than efficient conciseness.

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?

Five undocumented parameters, no output schema, and no annotation gaps mean the description is the only place filter, pagination, and return-shape context could live — and it provides none. An agent knows the high-level intent but not how to filter or page, which is a real gap for a list 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 0% across five parameters (name, type, startAt, maxResults, projectKeyOrId), so the description carries the full burden of explaining them — and it explains none. The only hint is the visibility scope, which does not clarify whether name is a substring filter, how startAt/maxResults paginate, or why projectKeyOrId narrows results; the single enum on type is left uninterpreted as well.

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 states a specific verb and resource ("Lists boards") and adds a scope qualifier ("visible to the current user"), which is enough to distinguish it from mutating siblings like createJiraBoard. It does not, however, differentiate itself from closely related siblings such as listJiraBoardSprints or getJiraBoardConfig, leaving the agent to infer the boundary.

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?

There is no statement of when to use this tool versus alternatives (e.g., getJiraBoardConfig for a single board's configuration, listJiraBoardSprints for a board's sprints) and no mention of prerequisites such as required Jira scopes or permissions. Usage is only implied by the name.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the state-filter behavior, and says nothing about pagination despite startAt/maxResults existing, nor about return volume for large boards.

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 short sentence, front-loaded with the resource and scoping, with zero filler. Appropriately sized for a simple list tool.

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?

No output schema exists, so the description should describe return shape or at least pagination semantics, and it does neither. With 0% schema coverage and no annotations gaps left, the definition is adequate to identify the tool but thin for calling it correctly on large boards.

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 carries the full burden, yet it only explains the state enum. boardId (the sole required param), startAt, and maxResults go completely unexplained - notably the two pagination params, which materially affect invocation.

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 resource (sprints), its source (a board), and the filter dimension (state). An agent can distinguish it from getJiraBoardSprintData and manageJiraSprint by the list-vs-get/manage verb, though the description never names those siblings 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: fetch sprints belonging to a board, optionally narrowed by state. No when-to-use/when-not guidance and no routing to the sibling tools that also touch sprints (getJiraBoardSprintData, manageJiraSprint).

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the permission-scoping trait ('visible to the current user'), which is genuinely useful, but says nothing about pagination defaults or result shape for a list endpoint.

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 front-loaded sentence with no wasted words, though its brevity is achieved by omitting information rather than by being efficient.

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?

For a 3-parameter listing tool with no output schema and no annotation coverage of filtering behavior, the description leaves the agent without pagination semantics, filter semantics, or result expectations. It is under-specified for the tool's complexity.

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% and the description adds no meaning for any of the three parameters. An agent gets no help understanding startAt/maxResults pagination or that dashboardName is a filter, which is exactly the gap the description should fill at low 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?

The description names the specific resource (Jira dashboards) and scopes it to those 'visible to the current user', so an agent understands the operation despite the verb 'list' only appearing in the name/title. It does not differentiate from siblings like listJiraFilters or listJiraBoards, which are superficially similar listing tools.

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?

'for discovery and linking workflows' gestures at a context but never states when to call this instead of listJiraFilters, listJiraBoards, or searchJiraIssuesUsingJql. There are no exclusions, prerequisites, or alternative-selection guidance.

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?

The annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds the visibility scope and a partial return description ('IDs and JQL'), but says nothing about pagination, default result caps, or what a caller does with the returned JQL.

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 front-loaded sentence that carries the resource, the scope, and the return shape with no filler. Nothing to trim.

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 no output schema, the 'returning IDs and JQL' clause is useful, but three parameters remain opaque and there is no pagination guidance for a tool that returns lists. Adequate for a simple list call, but leaves real 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 coverage is only 25% – only accountId has a description ('Filter by owner'). startAt, filterName, and maxResults are undocumented in both the schema and the description, and the description never compensates, so an agent gets no meaning for three of four parameters.

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 ('Search') and resource ('saved filters') with a scope qualifier ('visible to the current user') and even previews the return shape ('IDs and JQL'). No sibling tool deals with saved filters, so confusion risk is low, though the description never explicitly contrasts itself with any sibling.

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?

There is no when-to-use or when-not-to-use guidance, no mention of pagination behavior, and no hint that this is the entry point for obtaining a filterId used elsewhere. The visibility scope is stated but that is a constraint, not usage guidance.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds real behavioral value beyond them by stating the result is 'paginated oldest-first', which tells the agent about ordering and pagination. It does not explain result volume, page sizes, or how to page further.

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 front-loaded sentence with no filler or repetition. It is appropriately terse, though at the cost of the detail needed elsewhere; the awkward 'An work item's' phrasing is a minor blemish.

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?

For a simple paginated read with read-only annotations and no output schema, the description covers ordering and pagination, which are the key behaviors. It is nonetheless thin given 0% schema coverage and no explanation of the parameters or what a changelog entry contains.

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 schema contributes nothing and the description must compensate — but it only hints at pagination via 'paginated', never explaining startAt or maxResults, and never clarifying that issueIdOrKey is the required issue identifier. This leaves all three parameters effectively undocumented.

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 names the resource precisely — a work item's field-change history — so an agent can tell this returns changelog entries rather than comments or worklogs. It lacks any explicit verb ('list') and offers no differentiation from sibling read tools like getJiraIssue, but the scope is clear from the noun phrase and pagination note.

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?

There is no when-to-use guidance, no mention of prerequisites like needing the issue key in hand, and no routing to or away from siblings such as listJiraIssueWorklogs or listJiraIssueComments. The agent must infer usage entirely from the name.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The one piece of added context is 'Paginated', which usefully flags paging behavior, but the description says nothing about ordering defaults, result shape, or rate limits.

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 compact sentence with no filler and the key pagination framing front-loaded. It is efficient, though so terse that it borders on under-specification for a 5-parameter tool.

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?

For a tool with 5 parameters at 20% schema coverage and no output schema, the description is far too thin. It neither explains paging controls nor parameter usage, leaving real gaps an agent must guess around.

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 only 20% across 5 parameters (only orderBy is annotated). The description adds no meaning for startAt, maxResults, expand, or issueIdOrKey beyond the word 'Paginated', so it fails to compensate for the low 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?

The description names the resource (comments) and scope (for a Jira work item) and adds 'Paginated', but it is essentially a noun-phrase restatement of the tool name with no explicit verb and no differentiation from siblings like addOrEditJiraIssueComment. An agent can infer it is a read/list operation, but the phrasing is thin.

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 guidance and no reference to alternatives. It never clarifies the relationship to addOrEditJiraIssueComment (the mutating counterpart) or to other list tools such as listJiraIssueWorklogs or listJiraIssueChangelogs. The agent must infer usage entirely.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety and idempotency profile. The description adds little beyond confirming this is a read of link-type metadata; it doesn't mention scope (global vs project-specific) or freshness of the data.

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 short sentence is appropriately sized and front-loaded, but it's a fragment ('Available work item link types in Jira.') rather than a complete statement of what the tool does. There's no waste, but also very little substance.

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?

For a zero-param read tool with annotations and no output schema, the description should at minimum state that it lists link type names/IDs usable when creating issue links. As written, it lacks the return-value hint that would connect it to createJiraIssueLink, leaving a gap an agent must fill by assumption.

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?

Zero parameters, so baseline is 4. There are no parameter semantics to add, and the description doesn't need to compensate for anything here.

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 the resource ('link types in Jira') but the verb is implied rather than explicit; 'Available' hints at listing but doesn't commit. It's vague about whether it returns all available types or a filtered subset, and doesn't distinguish from siblings like createJiraIssueLink or listJiraIssueRemoteIssueLinks.

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 or when-not-to-use guidance. An agent can't infer from the description alone whether this should be called before createJiraIssueLink to discover valid link type names, which is the obvious use case given the sibling tools.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds no further behavioral context such as pagination, return format, or rate limits.

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?

It is a single short fragment with no waste, but it is under-specified rather than appropriately concise for a tool with an undocumented parameter. Front-loaded, yes, but insufficiently informative.

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 a simple read tool with annotations covering safety, the description is too minimal to help an agent select it among dozens of sibling tools. It does not explain what remote links are or when to use this versus getJiraIssue or listJiraIssueLinkTypes.

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?

The single required parameter issueIdOrKey has 0% schema description coverage. The description mentions 'Jira work item' which loosely hints at the parameter, but does not explain its format or meaning beyond that.

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 identifies the resource ('remote links associated with a Jira work item') which distinguishes it from siblings like listJiraIssueLinkTypes and createJiraIssueLink. It lacks an explicit verb, relying on the tool name, but a human or agent can infer the list operation.

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 guidance, no alternatives mentioned, and no prerequisites. The description is a bare fragment with no routing information.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing on top of that: no note that it returns only transitions currently valid for the issue's present status, no permission requirements, no ordering guarantees.

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 front-loaded sentence with no filler or redundancy; nothing could be cut. It is concise to a fault rather than verbose, so the shortness is under-specification rather than a structural flaw.

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?

For a one-parameter read tool with annotations covering safety, the description is minimally adequate, and it does at least say what is returned (available transitions). But with no output schema, it should say that the result feeds transitionJiraIssue and what identifiers the transitions carry — the one piece of context an agent actually needs.

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 carries the full burden for the single issueIdOrKey parameter. 'For a Jira work item' hints at what the parameter identifies but never states that it accepts either a numeric ID or a project key, or the format/constraints of either.

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 phrase 'Available workflow transitions for a Jira work item' names a specific resource (workflow transitions) scoped to a specific entity (a Jira work item), and the tool name supplies the 'list' verb. It is clear what the call retrieves, but it does nothing to distinguish itself from the sibling transitionJiraIssue, which is the natural confusion pair.

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?

There is no guidance on when to call this versus transitionJiraIssue, nor any stated prerequisite (e.g. call this first to discover valid transition IDs, then apply one). The one sentence is purely descriptive and leaves the agent to infer usage from the 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds one non-annotation trait, that results are paginated, but says nothing about ordering, page size defaults, or what happens when the issue has no worklogs.

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 front-loaded sentence with no wasted words, and the pagination trait is stated up front. It is arguably too terse for a 5-parameter tool, but nothing is padded.

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 no output schema and 40% parameter coverage, the description should carry more weight for a tool whose paging fields and time-window filters are undocumented. The read-only annotations cover the risk profile, but an agent gets no help on how to page or filter 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 only 40%: startedAfter and startedBefore carry 'Epoch millis', while issueIdOrKey, startAt and maxResults are bare. The word 'Paginated' hints that startAt/maxResults exist but the description never explains their semantics, so it fails to compensate for the coverage gap.

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 clear verb+resource (list worklogs / logged time) and scopes it to a Jira work item, with a useful gloss clarifying that 'worklogs' means logged time. It does not explicitly differentiate itself from the sibling addOrEditJiraIssueWorklog, so it stops short of a 5.

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 no when-to-use guidance, no prerequisites, and never names an alternative such as addOrEditJiraIssueWorklog or listJiraIssueComments for adjacent read needs. Usage is only inferable from the name.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful surface-level context about the shape of the returned data (IDs, names, work item counts, ownership), but says nothing about pagination, result caps, or permissions needed to enumerate project components.

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 compact sentence with no filler, and the most important information (which components) leads. Its only inefficiency is that the truncated phrasing loses the 'list project' framing an agent would want front-loaded.

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 no output schema, the description must carry return-value information, and it does sketch the fields returned. However, it omits the only parameter's semantics and any listing behavior, which is a meaningful gap for a project-scoped enumeration 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 0% and the single parameter is undocumented in the schema. The description mentions 'a space' but never says that projectIdOrKey accepts either a numeric project ID or a project key, leaving the only required input ambiguous.

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 fragment 'Components in a space' names the resource but supplies no verb and uses 'space', a non-Jira term, instead of 'project'. It also does not distinguish itself from close siblings such as listJiraProjectVersions or listJiraProjectIssueTypesMetadata; the returnable fields (IDs, names, counts, ownership) are listed, but the operation itself is only implied.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the ~40 sibling tools. An agent must infer usage entirely from the tool name.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that - no note on whether results are cached, paginated, or scoped per project - so it contributes no behavioral context of its own.

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 short front-loaded sentence with no filler, which is efficient. But the brevity tips into under-specification rather than true conciseness - it is terse at the cost of the information an agent actually needs.

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?

For a read-only listing tool with one required parameter and no output schema, the description should at minimum tie the result to projectIdOrKey and hint at the shape of what is returned (issue type names/ids). Neither is present, leaving the definition 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 0% and there is one required parameter, projectIdOrKey, which the description never mentions. It does not clarify that the identifier accepts either a numeric ID or a project key, nor that the listed types are scoped to that project.

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 conveys the resource (work item types) and its scope (within a Jira space), so an agent can roughly tell it apart from issue-focused siblings. However it omits an explicit verb ('list' is only implied) and uses 'space' rather than 'project', even though the parameter is projectIdOrKey, which blurs what entity is being queried.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the closest alternatives such as getJiraIssueTypeMetaWithFields or listJiraProjects. The agent must infer from the name alone that this is the lookup for issue-type metadata per project.

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, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds one useful behavioral detail - results are scoped to what the current user can see - but omits pagination behavior despite the presence of startAt/maxResults.

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 tight sentence with no filler. It is appropriately sized, though arguably under-specified rather than genuinely concise given the tool's parameter set.

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 no output schema, three parameters (two undocumented), and only a one-line description, an agent lacks enough to invoke this correctly - notably whether the result set is paginated or how to iterate beyond maxResults.

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 only 33%: 'query' is documented, but 'startAt' and 'maxResults' have no schema description. The tool description adds nothing about any parameter, so the two pagination controls remain unexplained in both places.

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 clear verb ('Get') and resource, but calls it 'Jira spaces' while the tool name and the schema field ('project name or key') say 'projects'. The terminology drift creates ambiguity, and there is no differentiation from the many sibling list/get tools.

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?

There is no guidance on when to use this tool versus alternatives such as listJiraProjectComponents or getJiraProjectVersions, and no prerequisites or exclusions are stated. The agent must infer the use case entirely from the name.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only the semantic framing that statuses belong to a work item's workflow, with no note on whether results are global or workflow-scoped, or how large the list may be. With annotations carrying the burden, a 3 is appropriate.

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 short sentence with no filler and no redundancy, so every word earns its place. Its compactness is also a limitation, but nothing is padded or buried.

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?

This is a simple read-only list tool with no output schema and full schema coverage, so the description does not need to explain returns. It is minimally adequate but omits the project-scoping behavior and any hint about the shape of the returned statuses, leaving the agent with just enough to call 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 description coverage is 100%, so the single projectIdOrKey parameter is already documented in the schema as scoping to one project's workflow statuses. The description contributes nothing about this parameter, and none is required. Baseline 3 applies when the schema does the heavy lifting.

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 names the resource (Jira statuses) and implicitly the action (list), making the tool's output immediately clear. It does not need to distinguish itself from siblings, since none of the other listed tools return statuses. The phrasing is a noun clause rather than a verb-first statement, which keeps it just short of a 5.

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?

There is no statement of when to use this tool, when not to, or what the alternative is. It also never mentions that the result can be scoped to a single project workflow, which is the main usage decision here. The agent must infer intent entirely from the name.

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?

The annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered and the description does not contradict it. However, the description adds no behavioral context beyond the annotations — nothing about ambiguous name matches, permission requirements, or what the lookup returns.

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 efficient sentence with the resource and lookup keys front-loaded and no wasted words. It is appropriately sized for a simple lookup tool, though it could carry one more clause of routing guidance without bloating.

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?

For a simple lookup with no output schema, the description covers the core operation adequately. It is incomplete regarding the undocumented maxResults parameter and the fact that name lookups can return multiple/ambiguous results.

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 only 50%: query is described but maxResults is undocumented in both schema and description. The description's 'display name or email' merely restates the query field, so it does not compensate for the missing maxResults semantics (defaults, limits, pagination).

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 states a specific verb (look up) and resource (Jira user account ID) plus the accepted input forms (display name or email). It is clear on its own, but it does not differentiate itself from the adjacent getJiraUser / getJiraCurrentUser siblings that plausibly retrieve user data.

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?

There is no when-to-use guidance and no mention of alternatives, despite several nearby tools (getJiraUser, getJiraCurrentUser) that an agent could confuse this with. The agent is left to infer that this tool specifically resolves a name/email into an accountId.

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=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is largely covered. The description adds only the operation list, which duplicates the schema enum, and says nothing about per-operation behavior, that release/archive mutate stored state, or whether operations can be repeated safely.

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 front-loaded sentence listing the operations with no filler. It is efficient, though the operation list is partly redundant with the enum and the sentence could have used its remaining budget for usage or prerequisite context.

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?

For a seven-parameter, four-operation mutation tool with no output schema, the description omits the required-parameter mapping per operation, the effect of release/archive, and any error or response context. The safety annotations cover part of the burden, but an agent still lacks enough to choose an operation confidently.

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 71% and the enum plus per-parameter notes ("Required for create", "Required for update/release/archive", date formats) already carry most semantics. The description contributes no additional parameter meaning, so it sits at the baseline for a schema that largely documents itself, with only the bare "description" field left undocumented.

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 names four specific verbs (create, update, release, archive) and the resource (a release/fix version), so the tool's scope is immediately legible. It is weakened by the odd term "space version" where the tool name and annotations say "Jira Project Version", which could confuse an agent, and it draws no boundary against sibling version tools such as getJiraProjectVersions or manageJiraProjectVersionRelatedWork.

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?

It enumerates what the tool can do but never says when to choose it over alternatives (getJiraProjectVersions for reads, manageJiraProjectVersionRelatedWork for related work) or how to pick an operation. No prerequisites, no when-not-to-use guidance.

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 readOnly=false, openWorld=true, idempotent=false, and destructive=false, so safety is covered. The description adds essentially nothing beyond that: no note on required permissions, whether updating overwrites existing fields, or what happens to the URL/title on update — the interesting behavioral questions for a non-idempotent mutation.

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 tight sentence with no filler and the action front-loaded. It is concise, but the brevity borders on under-specification rather than efficiency.

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?

For a five-parameter, non-idempotent mutation tool with 40% schema coverage and no output schema, the description is far too thin — it should carry the behavioral and parameter burden that annotations and schema do not, and it does not.

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 only 40%, and 4 of 5 parameters are required, yet the description mentions no parameter at all. It fails to compensate for the undocumented versionId, title, and url fields, nor does it explain the create/update toggle beyond what the schema's relatedWorkId description already states.

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 pair (create or update) and resource (related work links on a version), which lets an agent distinguish it from sibling read tools like getJiraProjectVersionRelatedWork and manageJiraProjectVersion. Minor friction: the description says 'space version' while the name and siblings use Jira project versions, creating a small terminology mismatch.

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 guidance on when to use this versus getJiraProjectVersionRelatedWork (read) or manageJiraProjectVersion (version CRUD). The create-vs-update condition is only implied, and that detail actually lives in the schema, not the description.

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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, carrying the safety profile. The description adds no further behavioral context such as permissions required, side effects of closing a sprint, or whether operations are reversible.

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 front-loaded sentence with no wasted words, appropriately sized for the tool surface. It could arguably be slightly more structured for a multi-operation tool, but it is efficient.

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?

For an 8-parameter, multi-operation mutation tool with 63% schema coverage and no output schema, the description is too thin. It does not map parameters to operations or explain operation-specific requirements, leaving significant gaps an agent must infer.

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 only 63%, so the description should compensate but adds nothing about parameter meaning. The verbs loosely correspond to the operation enum, but terms like 'populate' versus 'addIssues' create ambiguity, and nothing clarifies which fields apply to which operation.

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 names the resource (sprint) and enumerates the verbs the tool supports (create, populate, start, update, close), which maps to the operation enum. However, 'populate' only loosely maps to the 'addIssues' operation and it gives no differentiation from sibling tools like listJiraBoardSprints.

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?

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The list of operations restates what the schema enum already provides rather than telling an agent when this tool is the right choice.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context beyond that: no pagination cost, result limits, or query complexity caveats, even though the schema hints at paging via nextPageToken.

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 short sentence with zero waste, front-loading the verb and resource. It is arguably too terse rather than bloated, but structurally clean.

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?

For a JQL search tool with rich annotations and a well-described schema, the description is minimally adequate. It omits result-shape expectations and pagination flow, but with no output schema and strong annotation coverage, the remaining gaps are modest.

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 schema itself explains jql syntax, fields, maxResults default and nextPageToken. The description adds nothing about parameters, which is the expected baseline when the schema does the heavy lifting.

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 (search) and resource (Jira work items) plus the query language (JQL), so the action is unambiguous. However, it offers no differentiation from siblings such as getJiraIssue or listJiraIssueComments, which an agent might otherwise confuse with a lookup.

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 supplies no when-to-use guidance: nothing about when JQL search beats a direct getJiraIssue fetch, no mention of scoping, permissions, or limitations. The agent must infer usage entirely from the name.

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=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the safety profile is covered externally. The description adds useful scope information beyond that — that a comment can be attached and that sprint/backlog assignment is a possible side effect — but says nothing about failure modes (invalid transition IDs), required permissions, or the fact that repeating the call is not idempotent.

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 front-loaded sentence that wastes no words. It loses a point for the grammatical slip ('an work item') and the ambiguous 'and/or', which forces the agent to guess whether both effects can occur in one call.

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?

For a non-idempotent mutation with a nested free-form 'fields' object and no output schema, the description is thin: it never explains what 'fields' expects or how resolution-style objects tie into the status change. Annotations cover the safety profile and the schema covers most parameters, so it is minimally viable but not complete.

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 75%, with comments on 'transitionId' (pointing at listJiraIssueTransitions) and 'comment' and a bare-bones 'fields' placeholder. The description itself adds no parameter meaning at all — it never mentions transitionId, fields, or comment — so it does not compensate for the one undocumented parameter (issueIdOrKey). Baseline 3 applies when the schema does most of the work.

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 gives a specific verb and resource ('Transition an work item to a new status') plus a secondary capability ('assign it to a sprint or backlog'), so an agent understands the operation. It does not, however, differentiate itself from the closely related editJiraIssue sibling, which could also change status-like fields.

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?

There is no when-to-use guidance, no mention that listJiraIssueTransitions must be called first to obtain a valid transitionId (that hint lives only in the parameter schema), and no statement of when to prefer this over editJiraIssue. Usage is left entirely to inference.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lowered. The description adds nothing beyond that: no note that repeated calls create duplicate attachments, no size/type constraints, no indication of what the response contains.

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 short, front-loaded sentence with no filler. It is efficient, though the article error ('an work item') and the fully generic wording make it feel under-authored rather than tight.

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?

For a mutation tool with no output schema and two undocumented parameters, the description is far too thin: it never states whether the file replaces or supplements existing attachments, what happens on failure, or what a successful call returns.

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 only 33% — filePath is documented ('absolute path ... on the machine running this MCP server') but issueIdOrKey and mimeType have no descriptions. The description adds no parameter meaning at all, so it fails to compensate for the coverage gap.

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 gives a clear verb+resource ('Attach a local file'), and the tool name pins the exact target (Jira issue attachment). However, it says 'work item' rather than 'Jira issue', and it never distinguishes itself from the inverse sibling downloadJiraIssueAttachment.

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 guidance, no prerequisites (e.g. attachment permissions, file size limits), and no mention of alternatives such as downloadJiraIssueAttachment. The agent must infer all usage context from the 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 disclose that this is a non-read-only, idempotent, non-destructive, open-world operation, so the safety profile is covered structurally. The description adds nothing beyond that: it does not explain the effect of watching, whether it is reversible, who is watching after the call, or any auth/rate-limit context.

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 six-word sentence with no filler and the action front-loaded. It is efficient, though for a mutating three-parameter tool the brevity edges into under-specification rather than disciplined concision.

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?

For a state-changing tool with no output schema and a partially undocumented schema, the description is too thin: it omits the target resource type, the meaning of the toggle, permission requirements, and any note on what the call returns or how errors surface.

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 only 67%, and the description supplies no parameter meaning at all. Notably, issueIdOrKey has no schema description and is not clarified by the description, leaving the required identifier undocumented; the description could have explained the watch boolean or the accountId default but does not.

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 names a specific verb pair (watch/unwatch) and a resource (work item), so an agent can tell what the tool does at a glance. No sibling tool performs this operation, so it is distinguishable by default, though the description never says 'Jira issue' explicitly and offers no comparison to the other ~40 Jira tools.

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?

There is no statement of when to use this versus alternatives, no prerequisites (e.g., permission needed to watch), and no guidance on the toggle direction beyond the schema's own 'watch' parameter. The description only implies usage by describing the action itself.

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