Laraue Boards

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

With no annotations, the description carries the full behavioral burden. It does disclose the write nature and the return value (id) and the size limit, but says nothing about authorization requirements, who the comment is attributed to, whether posting triggers notifications, or whether the operation is 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?

Two short sentences, front-loaded with the action and the result. The trailing sentence largely restates the schema's maxLength, a minor redundancy, but the text is otherwise 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 simple two-parameter create tool with no output schema, the description covers purpose, return value, and the input limit. It omits side effects (attribution, notifications) and any error/authorization behavior, so it is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters (issueKey, text) are already fully documented with format hints ('BRD-42') and the maxLength constraint. The description only repeats the 4096-character limit, adding no semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb (creates) and resource (comment on an issue) plus the return value (its id). It is clear on its own, though it does not explicitly distinguish itself from siblings like edit_comment or list_issue_comments.

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. The description never mentions the alternatives in a crowded comment lifecycle (edit_comment, delete_comment) or any prerequisite such as an existing issueKey.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool creates a new issue and returns its key, and that it requires canCreateIssue on the space. It does not mention side effects (e.g., notifications), whether creation is transactional, rate limits, or what happens on validation failure. This is a mutation tool, so more detail would be helpful.

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

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

The description is two sentences, front-loaded with the core action and return value, followed by the prerequisite. Every sentence earns its place; no repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a create tool with no annotations and no output schema, the description covers the essential action, return value, and a required permission. It could be slightly more complete by mentioning that files are attached, or by hinting at validation constraints already in the schema (max lengths, file types). However, the schema handles parameter details thoroughly, so this is close to 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 schema has 100% description coverage; every parameter is fully described in the input schema. The description adds no parameter-level semantics beyond what the schema already states. Per the rules, with high schema coverage the baseline is 3.

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 uses a specific verb+resource ("Creates a new issue") and adds a scope detail: the issue is created in the space the given status belongs to, and it returns the issue key. It is clear, though it doesn't explicitly contrast with the sibling edit_issue or create_comment, so it falls short of perfect sibling differentiation.

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 states the prerequisite permission (canCreateIssue) and points to list_spaces for context, which gives some usage context. However, it does not say when to use this tool versus alternatives like edit_issue, nor does it mention any exclusions or typical call flow beyond the permission note.

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?

With no annotations, the description carries the full burden, and it delivers: it discloses the permanent effect (cannot be undone), the visibility change (stops appearing except in audit history), and the author-only permission constraint. This is comprehensive for a destructive operation and contradicts nothing.

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

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

Three tight sentences front-load the core action, then add irreversibility, permission, and alternative routing. Every sentence carries essential information with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-parameter delete tool with no output schema and no annotations, the description covers the action, consequences, permission, and alternative. Nothing an agent needs to call it correctly is omitted.

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 schema already fully documents commentId as 'The comment's id, from list_issue_comments,' so with 100% coverage the baseline is 3. The description mentions list_issue_comments again in the context of canManage, but adds no new parameter-specific semantics beyond what the schema provides.

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 precise action ('Deletes a comment') and the resource, and differentiates it from the sibling 'edit_comment' by directing the user to that alternative for text changes. It also clearly notes the irreversibility and the audit-history retention, making the tool's scope unambiguous.

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 provides explicit when-to-use guidance: delete vs. edit ('To just change its text instead, use edit_comment'), and a prerequisite check ('Only the comment's own author can delete it - check canManage in list_issue_comments before calling'). This fully instructs the agent on selecting this tool versus alternatives.

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?

With no annotations, the description carries the full burden of disclosing behavior, and it does so well: it explains the destructive effect, notes the audit-history exception, and states the required permission. It does not cover cascading effects or reversibility, but for a one-parameter delete operation the key behavioral facts are present.

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

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

The description is two short sentences with the core action front-loaded, followed by the permission note. Every clause earns its place and there is no filler or redundancy.

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 one-parameter delete tool with no output schema, the description covers the purpose, the behavioral effect, and the authorization requirement. It does not describe the success/failure response or discuss sibling alternatives, but these are minor gaps given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the only parameter, issueKey, is already documented with a format example. The description adds no parameter-level meaning beyond what the schema provides, so it neither enhances nor detracts from the schema's 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 clearly states the action 'Deletes an issue' and adds a useful behavioral clarification: the issue stops appearing everywhere except its audit history. It is specific about the verb and resource, but it does not explicitly differentiate from sibling mutating tools like edit_issue or create_issue, 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 intended use is implied: call this when an issue needs to be removed. The permission prerequisite, 'Requires canDelete', and the pointer to get_issue/list_issues provide useful context, but the description gives no explicit guidance about when not to use it or which alternative tool to prefer instead, leaving selection 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?

No annotations exist, so the description carries the full behavioral burden. It does disclose a real permission constraint (author-only) and the length cap, which is meaningful. It omits what happens on rejection, whether the prior text is recoverable, and what a successful call 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?

Two sentences, zero filler, and the action is front-loaded ahead of the constraint and the permission caveat.

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 two-parameter edit with no output schema and no annotations, the description covers what is edited, the limit, and the authorization gate. Only the success/failure outcome is left unstated, which is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters are documented in the schema itself, so the baseline is 3. The description restates the 4096 limit already present in the schema and only hints at where commentId comes from.

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

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

States a specific verb and resource ('Edits a comment's text') with a scope constraint (max 4096 characters). It is clearly distinguishable from edit_issue or create_comment by resource, though it never explicitly contrasts itself with those siblings.

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

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

Gives a concrete precondition: only the comment's own author can edit it, and it routes the agent to list_issue_comments / canManage to verify that before calling. No explicit when-not or alternative-tool guidance beyond that, but the usage condition is actionable.

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?

With no annotations, the description carries the full burden and mostly delivers: it discloses destructive replacement semantics (not append/merge), the pre-fetch workflow to avoid data loss, the required title to preserve, an explicit permission prerequisite (canEdit), and the scope limit (status unchanged). It stops short of stating what happens to existing attachments or attribute side effects, but the core mutation risk profile is well disclosed.

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?

Five short sentences, zero filler, and the most important fact (full replacement, not merge) is front-loaded before the workflow and permission notes. Every sentence adds a distinct constraint or behavior.

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 annotations and no output schema, the description covers the critical gaps: replacement semantics, the destructive data-loss risk, the canEdit requirement, and the status boundary. Attachment and attribute handling are left entirely to the (fully covered) schema, which is a minor gap given 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 100%, so the schema already documents all seven parameters, including the title-preservation note and attachment/attribute semantics. The description's title guidance largely duplicates the schema's own 'Required - pass the current title to keep it' text, adding little beyond the baseline. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Fully replaces an issue's text content') and immediately disambiguates the operation type ('not an append or merge'). It also separates the tool from the sibling edit_issue_status by stating 'Does not change status.' An agent can distinguish it from edit_comment, create_issue, and edit_issue_status without opening any 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?

Explicit routing guidance: fetch get_issue first if content must be preserved, pass the current title from get_issue to keep it, and requires canEdit (pointing at get_issue/list_issues for the check). It also names the boundary condition (no status change) that would otherwise push the agent to edit_issue_status.

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?

With no annotations, the description carries the full burden and does add useful behavior: the permission requirement and the fact that a comment can be posted atomically in the same call. It is silent on side effects such as history entries, notifications, or what happens on an invalid statusId, so mutation behavior is only partially disclosed.

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

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

Two tight sentences with the core action front-loaded and the permission caveat second; nothing is redundant or padding.

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 annotations and no output schema, the definition covers purpose, permission, and the optional comment but leaves failure modes and downstream effects unexplained. It is minimally adequate 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?

Schema description coverage is 100%, so the schema already explains issueKey format, the comment's max length and purpose, and where statusId comes from. The description's 'by id' and 'optionally posting a comment in the same call' restate rather than extend that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Moves an issue to a different status by id') plus the optional comment side-effect, which is far more informative than the bare name. It does not, however, contrast itself with the neighboring edit_issue tool, so sibling differentiation is left to inference.

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 a precondition ('Requires canEdit') and points to get_issue/list_issues for permission checking, which is genuine usage context. It never states when to choose this tool over edit_issue or list_statuses, nor any exclusions, so the guidance remains implied rather than explicit.

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?

With no annotations present, the description carries the behavioral disclosure burden. It usefully adds that only image attachments are currently supported and that the content returned is the original file content, implying a read/download operation. However, it does not mention authentication needs, failure modes for unsupported attachment types, or whether the response is binary/base64/streamed.

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

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

Two sentences convey the action, the source of the id, and the image-only limitation with no redundancy. The core operation is front-loaded, and every clause adds useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, the description covers what the tool does, where the id comes from, and the main current limitation. It does not describe the exact output format or error behaviors, but for this level of simplicity, the description is nearly complete and would let an agent call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description mirrors the schema's guidance that attachmentId comes from get_issue or list_issue_comments. The description adds some context about the file content being original, but it does not substantially go beyond the structured parameter description, so the baseline 3 is appropriate.

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

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

The description clearly states the verb ('Downloads'), the resource ('an attachment's original file content'), and the exact source contexts (get_issue attachments or list_issue_comments attachments). It precisely identifies what the tool does and how it differs from the surrounding issue/comment 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?

The description gives clear usage context: use this when you have an attachment id from get_issue or list_issue_comments and need the original file content. It also provides a behavioral constraint ('Only image attachments are supported today'), which is an implicit when-not-to-use signal, though it does not explicitly name alternatives or exclusions.

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

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

With no annotations and no output schema, the description carries the full disclosure burden and does it well: it enumerates the returned fields and explains the meaning of statusCategory (Created/InProgress/Completed) and the purpose of canEdit/canDelete and url. It omits error behavior (e.g. non-existent key) and permission requirements, keeping it out of the top band.

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

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

One sentence, front-loaded with the core action and key, then the return details. The parenthetical cross-references make it dense but each clause adds a distinct fact, so little 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?

For a single-parameter read tool with no output schema and no annotations, describing the returned payload and its cross-tool references is exactly the missing piece an agent needs. Nothing essential to correct invocation is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single issueKey parameter, so the schema already documents format and semantics; the description only restates the same 'BRD-42' example. 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?

States a specific verb and resource ('Gets one issue's title, full content and attachments') with the lookup key, and 'one issue' clearly distinguishes it from list_issues and get_issue_history in the sibling set.

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?

Points the agent to the right follow-on tools for data it does not return (comments via list_issue_comments, attachments via get_attachment/edit_issue's removeAttachmentIds), which is effective routing. It does not explicitly say when to prefer this over list_issues, so it stops short of full when/when-not 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?

No annotations exist, so the description carries the full disclosure burden and meets it thoroughly. It reveals ordering behavior (newest first), pagination limits (50 per page, hasNextPage), entry composition (when, who, API key attribution, what operation, readable change lines), and a truncation behavior ('Long content is shortened').

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

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

The definition is information-dense with no filler: every clause contributes (scope, ordering, pagination, entry fields, examples, truncation). It is a single long sentence that could be split for readability, but 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 no annotations, the description must carry the full burden of explaining the return shape, and it does: entry fields, field semantics, representative change-line examples, and truncation behavior are all specified. An agent has everything needed to call and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline of 3 applies. The page and count descriptions in the schema already explain their semantics well; the tool description adds context about the 50-per-page default and hasNextPage linkage, but does not materially extend what the schema 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?

The description gives a specific verb-resource pair ('Lists an issue's change history') and clarifies scope ('the issue and its comments'), which distinguishes it from siblings like get_issue (current state) and list_issue_comments (comments only). The ordering and pagination details further pin down exactly what this tool returns.

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 provides concrete operating instructions: newest-first ordering, a 50-entry page cap, and how to detect more pages via hasNextPage. It does not explicitly name sibling alternatives or state when not to use this tool, but the pagination and filtering context is clear enough for an agent to invoke it correctly.

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?

With no annotations, the description carries the full burden. It clearly indicates this is a read operation (returns information) and lists the exact data points returned, including user id, display name, and organization details. It does not mention side effects or limitations, but for a pure identity lookup this is adequate.

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

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

The description is a single, information-dense sentence that front-loads the core purpose and then explains the usability of the user id. It is concise and well-structured, covering all essential aspects without unnecessary fluff.

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 there is no output schema, the description is the sole source of return information. It enumerates the key fields (user id, display name, organization id/name/personal flag) and even provides a practical use case, making it complete enough for an agent to invoke and interpret the result.

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 has zero parameters, so schema coverage is trivially 100%. The description adds no parameter details, but none are needed. Per the baseline for 0 parameters, a score of 4 is appropriate.

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

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

The description states a specific verb ('Returns') and a clear resource ('who you are'), detailing exactly what is returned: user id, display name, and organization details. It is distinct from all sibling tools, which focus on issues, comments, attachments, etc., so there is no ambiguity about its purpose.

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 a concrete usage hint by noting the user id is usable as list_issues' assigneeId to find your own issues, which implies when to use this tool. While it doesn't explicitly state when not to use it, there are no alternatives for identity retrieval, so the context is sufficient.

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?

With no annotations provided, the description carries the burden of disclosing behavioral traits. It states the tool is a read-only listing operation and describes the return format (id, name, type, allowed values). However, it does not mention potential pagination, rate limits, or authentication requirements, which could be relevant. The description adds value beyond the minimal information but is not exhaustive.

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

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

The description is concise, two sentences, with the core purpose front-loaded. The second sentence adds valuable context about how the output is used. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description's explanation of the return fields and its relevance to issue creation is quite complete. The only minor gap is the lack of mention of ordering or any potential list size limits, but for a simple listing tool, this is sufficient.

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 has zero parameters, so the schema provides no parameter semantics. The description compensates by clearly explaining the output structure and its relation to create_issue/edit_issue. This is excellent for a no-parameter tool, earning a 4 rather than the baseline 4 for zero params.

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 clearly states the tool's purpose: it lists custom issue attributes for the caller's organization, specifies the exact fields returned (id, name, type, allowed values), and directly connects it to the attributes parameter used by create_issue/edit_issue. This is specific and differentiates it from sibling tools like list_issues or list_statuses.

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 implicitly explains when to use this tool: when you need to know the valid attributes for create_issue or edit_issue. It does not explicitly mention alternatives or when not to use it, but the connection to those sibling tools provides clear context. A score of 4 reflects the clear context without explicit exclusions.

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?

With no annotations, the description carries the full burden and does well: it discloses permission scoping ('every space the caller can read'), ordering (by space key), page size cap, and the hasNextPage continuation signal. It doesn't discuss auth specifics or failure modes, but the read-only nature and pagination behavior are clear.

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 dense sentence, front-loaded with the verb and scope, then pagination, then the return shape. Every clause carries information; nothing is padding.

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 describing the returned fields (id, name, spaceKey, isDefault, status with its enum values) plus pagination and ordering is exactly what an agent needs to call and consume this tool. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning the schema lacks: it explains that the returned epic id is what list_issues' epicId filter accepts and what isDefault denotes. That linkage is genuinely useful beyond 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 specific verb (Lists) and resource (epics), plus the scope variants (one space or every readable space). It is clearly distinguishable from siblings like list_issues and list_spaces, and even names the field that feeds list_issues' epicId filter.

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

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

Gives concrete routing guidance: omit spaceKey to span all spaces, pass page+1 for the next page, and check hasNextPage because pages cap at 50. It doesn't state when NOT to use it (e.g., when get_issue is a better fit), so it stops short of a full when/when-not/alternatives treatment.

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?

With no annotations provided, the description carries the full burden, and it delivers: pagination behavior, ordering, canManage semantics for mutation tools, comment fields, and attachment id usage with get_attachment. This gives an agent enough behavioral context to call and interpret the result correctly.

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

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

Two sentences, no filler, with the core listing behavior front-loaded and the valuable field/permission detail following directly. Every clause adds useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with no output schema and no annotations, this description is unusually complete: it explains pagination, result ordering, returned fields, permission implications, and how attachment ids relate to another tool. An agent has what it needs to invoke the tool and use the response.

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 schema already documents the three parameters clearly. The description adds general context about pagination and defaults but doesn't materially improve on the parameter-level documentation provided in 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 ('Lists'), the resource ('an issue's comments'), and key behavioral details ('oldest first', 'up to 50 per page'). This clearly distinguishes it from sibling tools like create_comment, edit_comment, and delete_comment, which have different purposes.

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 makes the tool's use context clear: retrieve an issue's comments with pagination, and use canManage to decide whether edit_comment/delete_comment is permitted. It doesn't explicitly state when not to use it, but the purpose is unmistakable relative to the sibling list.

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?

With no annotations, the description carries the full burden and does well: it discloses page size (up to 50), sort order (most recently updated first), pagination via hasNextPage, and that canEdit/canDelete reflect the caller's real permissions. It omits obvious caveats like read-only nature and any scoping/auth limits, but the behavioral disclosure is substantially richer than typical.

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

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

Front-loaded with purpose, then pagination, then return-field semantics in a logical flow. The third sentence enumerating return fields is dense but earns its place given no output schema; overall efficient with minimal waste.

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 no annotations, the description compensates by describing the return payload (title, canEdit/canDelete, statusCategory/statusCategoryId, url) and pagination signals. Combined with the fully documented input schema, an agent has everything needed to call and interpret 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 description coverage is 100%, so the schema already documents all seven parameters in detail (page, count, epicId, spaceKey, statusId, assigneeId, statusCategoryId). The description merely summarizes the filterable dimensions, adding little beyond what the schema provides, so the baseline 3 applies.

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

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

The description uses a specific verb and resource ('Lists issues in the caller's organization') and immediately scopes it with the available filters. An agent can distinguish this from siblings like list_epics, list_spaces, and get_issue without opening any 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?

Usage is implied: the filter parameters reference list_epics, list_spaces, list_statuses, and list_members, hinting at a workflow, and the pagination note implies iteration. But there is no explicit statement of when to use this versus get_issue or the other list_* tools, and no exclusions.

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?

No annotations are provided, so the description carries the full burden. It does disclose that results are scoped to members 'visible to the caller' and that the output provides ids for assignee fields. It does not mention pagination, output shape, or read-only status, but those are less critical for a simple list operation.

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

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

The description is short and front-loaded with the core action, which is good. However, the second clause is grammatically tangled: 'the ids list_issues' assigneeId filter, and create_issue/edit_issue's assigneeId, accept' makes the sentence harder to parse than it should be.

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 low-complexity tool with one optional parameter and a thorough schema explanation, the description plus schema is nearly sufficient. It clearly states the purpose and integration with assignee fields; the main gap is the lack of an output schema or explicit return-field explanation, though 'the ids' hints at the core output.

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 sole parameter spaceKey already has 100% schema description coverage, including what happens when passed versus omitted. The tool description adds no parameter-level meaning, but the schema already covers it fully, so the baseline of 3 is appropriate.

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

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

The opening phrase 'Lists organization members visible to the caller' clearly identifies the action and resource, and the second clause connects the result to assigneeId fields in list_issues/create_issue/edit_issue. This makes the tool's purpose unambiguous and differentiates it from the other list_* siblings.

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 tells the agent that the returned ids feed list_issues' assigneeId filter and create_issue/edit_issue's assigneeId, which is a clear when-to-use signal. The schema additionally explains when to pass spaceKey. There is no explicit exclusion statement, but no obvious competing member-listing sibling exists.

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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals that each space includes a canCreateIssue field reflecting the caller's actual permission, which is valuable for decision-making. It does not mention pagination or other side effects, but for a listing tool this is acceptable given its simplicity.

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

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

The description is two sentences with no wasted words. The purpose is front-loaded, and the cross-tool references are placed strategically. Every clause adds value.

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 parameterless list tool with no output schema, the description fully covers what it does, what it returns, and how it connects to sibling tools. No additional information is needed for an agent to correctly invoke 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?

The tool has zero parameters, so the baseline is 4. The description adds context about the return fields (space keys and canCreateIssue), which is helpful for understanding the output shape, though it does not need to explain parameters since there are none.

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 clearly states the tool lists spaces available to the caller and explicitly ties the output to the spaceKey filters of sibling tools (list_issues, list_statuses). This distinguishes it from other list_* tools by specifying the exact resource and its cross-tool utility.

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 implies usage context by noting that the spaces' keys are accepted by list_issues and list_statuses, and that canCreateIssue reflects the caller's permission. This gives an agent a clear reason to call the tool, though it does not explicitly state when NOT to use it.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the return shape (grouped by epic, per-status category and categoryId) which is genuinely useful given there is no output schema, but it says nothing about permissions, whether statuses are workspace- or space-scoped beyond the parameter, caching, or ordering of the epic grouping.

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 dense but well-structured sentence: the listing action and grouping are front-loaded, followed by id provenance and category semantics. Slightly overstuffed with multiple parenthetical cross-references, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only lookup with no output schema, the description covers the important ground: what is returned, how it is grouped, what each id feeds into, and the meaning of the category values. Only auth/permission expectations and any ordering guarantees are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single spaceKey parameter already carries an example ('BRD') plus its source ('from list_spaces') in its own description. The prose adds no further parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists the statuses in a space, grouped by epic') and immediately distinguishes itself from list_epics and list_issues by qualifying exactly which ids it returns and where they are consumed. An agent can tell this apart from its siblings without opening any 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 routes usage implicitly but clearly: the returned ids are the ones 'create_issue/edit_issue_status accept' and the categoryId is what 'list_issues statusCategoryId filter takes', so an agent knows this is a lookup step before creating/editing issues or filtering them. There is no explicit when-not-to-use statement or named alternative list tool, keeping it short of a 5.

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