Laraue Boards

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 the external effects on runners, the side effect of unlocking the issue for editing, the permission requirement (canEdit), and the false return on no-op. It stops short of stating whether a cancelled run can be restarted or what happens to the run record afterwards.

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

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

Four tightly packed sentences, front-loaded with the action and its state scope, followed by effects, return semantics, and permission. 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?

No output schema exists, and the description covers the return value (false on already-finished/cancelled), the permission prerequisite, and the state preconditions. That is everything needed to invoke it correctly.

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

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

Only one parameter with 100% schema coverage, and the schema already says where to obtain runId (list_agent_runs or get_issue's latestAgentRun). The description adds value by implying the run must be in an open state for the id to be actionable, though it does not restate the id's origin.

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+resource ('Cancels ... an agent run') and immediately scopes it to open runs in the Ready or Working state, which distinguishes it cleanly from siblings like finish_agent_run or claim_agent_run. An agent can tell what this does and when it applies without opening the schema.

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

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

Gives clear context: only applies to open (Ready/Working) runs, requires canEdit on the issue, and returns false if the run already finished or was cancelled. It does not explicitly name the sibling alternative (finish_agent_run) for the completed case, so routing is implied rather than 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?

No annotations exist, so the description carries the full burden and does so well: it documents the atomicity guarantee, the exact meaning of both return values, the blocked-issue edge case, the permission requirement (canEdit), and the assignee restriction. These are non-obvious runtime behaviors an agent could not infer from the schema.

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-loads the core action and its state change, then layers return semantics, atomicity, and constraints in short declarative sentences. Dense but every sentence carries operational information; no filler.

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

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

Despite having no output schema, the description fully specifies the boolean return and how to react to each value, plus the permission and identity preconditions and the recommended next call. Nothing needed to invoke it correctly is missing.

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

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

One parameter with 100% schema description coverage; the schema already explains runId and its provenance (list_agent_runs). The description adds no format or validation detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Claims) and resource (a Ready agent run), plus the resulting state transition (moving it to Working). Distinguishes itself from siblings like create_agent_run and cancel_agent_run by naming the exact lifecycle state it operates on.

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

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

Gives explicit when-to-act guidance (claim a Ready run, skip on false), the precondition (only the issue's assignee can claim; requires canEdit), and routes the agent to the follow-up tool by name: edit_issue_status. This is close to a complete decision procedure.

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 behavioral burden and does so richly: the run is created in Ready and later claimed, open runs lock the issue so edit_issue/delete_issue fail (but status changes and comments still work), blocked runs remain isBlocked until blockers are Completed, and it states the return value ('Returns the run'). This is exactly the mutation/permission/locking context an agent needs.

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

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

Front-loaded with the core action and effect, then layered with constraints in a logical order (state, exclusivity, blocking, locking, permissions). It is dense and long-ish, but nearly every clause carries a distinct constraint, 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 mutation with no output schema, the description covers lifecycle state, claim behavior, locking side effects, blocking semantics, and all preconditions, and explicitly notes it returns the run. Nothing needed to invoke it correctly is missing.

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

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

Only one parameter (issueKey) and schema description coverage is 100% ('The issue's key, e.g. BRD-42'), so the schema already fully documents it. The description adds no format or syntax detail beyond the schema, which matches the baseline-3 rule for high 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?

Names a specific verb+resource ('Hands an issue to the agent: creates an agent run'), states the resulting state (Ready), and immediately distinguishes itself from the sibling that picks up the work (claim_agent_run). An agent can separate it from cancel_agent_run/claim_agent_run/finish_agent_run 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 when-to-use and when-not: an issue can have only one open run, so cancel first; a blocked issue can still be handed off and its run waits as isBlocked; prerequisites are enumerated (only the assignee, requires canEdit, issue must be in a Created status, epic needs Created/InProgress/Review statuses) with pointers to get_issue/list_issues/list_statuses.

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: it discloses authorship/attribution in history, the required permission (canEdit), the not-found masking for unreadable issues, visibility to all readers, absence of notifications, and post-hoc ownership of edit/delete rights. This is exactly the behavioral context the schema and annotations cannot supply.

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 and return value, then permissions, then alternatives — good ordering with no filler sentences. Slightly dense in the parenthetical about key attribution and ownership, which packs three facts into one clause.

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, and the description compensates by naming the return value explicitly. Permission requirements, failure mode, visibility, and sibling routing are all covered for a 3-param mutation tool.

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

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

Schema coverage is 100%, so both required params are documented structurally; the description adds meaning beyond that by tying issueKey to the canEdit/readability precondition and by framing the returned id as the input to edit_comment/delete_comment. It says nothing extra about the files parameter, which the schema handles.

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

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

States a specific verb+resource ('Adds a new comment to an issue'), the identity it posts under, and the return value ('returns the comment's id'). It explicitly distinguishes itself from the closest siblings edit_comment and delete_comment by naming what they consume.

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 positive guidance ('discussion and progress notes') and explicitly routes three alternatives: edit_comment for changing a comment, edit_issue_status's comment for status-change justification, edit_issue for the issue body. An agent can pick the right tool without 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?

With no annotations, the description carries the load and does add real behavior: the permission gate, the implicit space resolution from statusId, and the fact that a key is returned. It omits side effects such as notifications, attachment processing, or failure modes for a missing/invalid status, which is the remaining gap for an unannotated mutation tool.

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, with the core action and scope stated first and the permission requirement second. Nothing could be removed without losing information.

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

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

With dense schema descriptions and no output schema, the description covers the essentials an agent needs: permission, space resolution, and the returned key. It stops short of describing error behavior or side effects, which for a creation tool leaves a small but real gap.

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 every parameter including files, assigneeId, and attributes is already documented in detail. The description adds no parameter-level meaning beyond what the schema states; its space-derivation note merely echoes the statusId description. 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 ('Creates a new issue'), plus a non-obvious scoping rule: the destination space is derived from the given status. It also declares the return value ('its key'), so an agent can distinguish it from edit_issue, create_issue_link, or create_comment 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?

Gives an explicit prerequisite ('Requires canCreateIssue on that space') and routes the agent to list_spaces for verification. It does not spell out when to prefer this over edit_issue or how to obtain a statusId beyond the schema's own pointer to list_statuses, so no exclusion guidance is present.

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 so: it discloses auth requirements, the one-link-per-pair constraint, the requirement to delete before re-linking, and the no-cycle rule for Blocks. These are exactly the behavioral traits an agent needs beyond the schema.

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-loads the core action and example, then layers permissions and constraints. Dense but every sentence earns its place given the tool's complexity; the permuted-relation enumeration is slightly heavy but necessary.

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 description covers the permission model, edge-case constraints, and correct invocation semantics. Nothing an agent needs to link issues correctly is missing.

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

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

Schema coverage is 100% so the schema already documents all three parameters, setting a baseline of 3. The description adds real value by clarifying relation directionality via the worked example and by explaining how swapping keys pairs with the opposite relation, linking parameter choices to intent.

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 ('Links two issues of the organization') and gives a concrete notation example ('BRD-7 BlockedBy BRD-3'). It is clearly distinguishable from all siblings, being the only link-creation tool.

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?

Specifies permission prerequisites (canEdit on issueKey, read access to otherIssueKey), provides a concrete workaround for the asymmetric-permission case with the exact relation mappings, and names the alternative delete_issue_link for changing an existing link's type.

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 provided, the description carries the full behavioral burden and does so: it discloses the soft-delete effect (disappears except in audit history), the permission gate, the runtime failure condition, and the remedy. This is well beyond a bare 'deletes an issue'.

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 short clauses, front-loaded with the action and its effect, then prerequisites and failure handling. No sentence is filler; each adds a distinct constraint.

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 mutation with no annotations and no output schema, the description covers effect, permissions, failure mode, and workaround. Nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter and schema description coverage is 100% ('The issue's key, e.g. BRD-42'), so the schema already fully documents it. The description adds no syntax or format detail beyond referencing sibling tools that surface the key, making the baseline 3 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?

States a specific verb (deletes) and resource (issue), then immediately clarifies the semantics of that deletion: the issue stops appearing everywhere except its own audit history. An agent can distinguish this from edit_issue or edit_issue_status without opening the schema.

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

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

Gives explicit preconditions and routing: requires canDelete (pointing at get_issue/list_issues to check), and it fails while the issue is handed to an agent, with the alternative named (cancel_agent_run first). This is exactly the when-to-use/when-not guidance the dimension asks for.

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 the permission model (canEdit on issueKey, read on the other) and the symmetry property (either issue can be issueKey; same link removed). It stops short of stating reversibility, idempotency, or error behavior for a tool operating on an existing relationship.

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, front-loaded with the action and scope, followed by the interchangeability and permission caveat. The parenthetical cross-references point to get_issue/list_issues for detail rather than bloating this entry, so every clause earns its place.

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

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

For a two-parameter, no-annotation, no-output-schema tool, the description covers purpose, scope, permissions, and parameter symmetry adequately. It could add whether the operation is idempotent or what a failure looks like, but nothing critical to correct invocation 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 real semantics beyond the schema: it explains that the two keys are interchangeable for the same effect and that the permission requirement differs depending on which key you place in issueKey. That is operational guidance the schema does not convey.

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 ('Removes the link between two issues') and clarifies scope ('whatever its type or direction'). It contrasts implicitly with the sibling create_issue_link but never names it or any other sibling, so an agent must infer the pairing from the name alone.

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 clear context for when this applies (unlinking two issues of any link type/direction) and supplies the prerequisites: canEdit on the issue passed as issueKey and read access to the other. It does not name an alternative tool or state exclusions, but the usage conditions are otherwise unambiguous.

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 behavioral disclosure burden. It adds the important author-only permission constraint, but does not state whether edits are reversible, what happens to existing text beyond replacement, or how attachment removal 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?

Two compact sentences with the core action and the critical authorization prerequisite front-loaded. There is no wasted language.

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, the description covers the essential precondition and the main effect. It could say more about replacement/removal side effects, but the schema supplies the detailed parameter semantics.

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 all four parameters in detail. The description adds only the max-length reminder and loosely mentions optional attachments, which is baseline value 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 uses a specific verb and resource: it edits a comment's text and optionally its attachments. It clearly distinguishes this from sibling tools like create_comment and delete_comment.

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 gives a clear precondition: only the comment's author can edit, and the caller should check canManage in list_issue_comments first. It does not explicitly compare against alternatives beyond that prerequisite.

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: it discloses destructive replacement semantics, the canEdit permission requirement, the precondition failure while an agent run is open, and the remediation (cancel_agent_run). This is exactly the operational context an agent cannot infer from the schema.

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

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

Front-loaded with the most consequential fact (full replacement), then prerequisites, then failure conditions. Every clause carries information; no filler.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers replacement semantics, auth requirements, prerequisites, and failure/remediation paths. The remaining field-level detail (attachments, attributes, assignee) is fully handled by the schema.

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 every parameter is already documented, giving a baseline of 3. The description reinforces the title-required and content-replacement semantics, but adds little beyond what the schema fields already state verbatim.

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 first sentence states a precise verb+resource+scope: 'Fully replaces an issue's text content - not an append or merge.' It explicitly distinguishes itself from the append/merge interpretation an agent might assume, and 'Does not change status' separates it from edit_issue_status.

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 names concrete alternatives and conditions: use get_issue first to preserve existing content, cancel_agent_run first when a run is open, and note that status changes belong elsewhere. When-to-use and when-not-to-use are both 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, 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, the description carries the full burden and does fairly well: it discloses the permission requirement (canEdit on the issue), the boolean return semantics including the race condition where the run is no longer Working because a person cancelled it, and that reason is discarded for Done. It doesn't say whether finishing is idempotent or what happens to the run's subsequent state, which keeps it out of 5 territory.

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

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

Three tight sentences, front-loaded with the action and its outcomes, then the false-return semantics, then the permission prerequisite. No filler.

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

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

For a mutation tool with no annotations and no output schema, the description covers the two things an agent most needs: the permission prerequisite and the meaning of the boolean return value, including the cancellation race. The remaining gap is what the run transitions to after a Done vs Failed finish and whether reason is surfaced anywhere.

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 runId, state, and reason are already fully documented in the schema, including the enum values and the max length. The description adds essentially nothing parameter-specific beyond what the schema says, so the baseline of 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 ('Finishes') and resource ('a Working agent run') with the two terminal outcomes it can produce (Done or Failed), which is well beyond a restatement of the name. It doesn't explicitly name cancel_agent_run as the sibling that produces the false path, but the reference to a person cancelling the run effectively implies the division of labor.

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 real invocation context: the run must currently be Working, and a false return means someone else cancelled it, so the agent should stop working. It lacks an explicit 'do not call this if...' or a direct pointer to cancel_agent_run, but the condition that selects this tool over that one is inferable.

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 substantial work: it discloses that the response shape varies by mime type — image for JPEG/PNG/WebP/GIF, plain text for Markdown/TXT/JSON, and an embedded base64 resource with mime type for PDF/DOCX/DOC. That is the single most important behavioral fact for an agent consuming the result. Gaps remain on auth requirements, size/rate limits, and failure modes for unknown types.

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 action front-loaded and the return-format detail following. The second sentence is dense with a parenthetical and a three-way list, but every clause carries actionable information an agent 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?

There is no output schema, so the description must explain returns — and it does so thoroughly, including the base64/mime-type fallback for non-image, non-text documents. For a single-parameter read tool this is nearly complete; only error handling and size constraints are 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% and the single parameter already documents its provenance ("from get_issue or list_issue_comments"). The description mostly restates that, adding only the mild clarification distinguishing an issue-level attachment from a comment-level one, which is already implied by the schema text. 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?

Specific verb + resource: "Downloads an attachment's original file content" by id, and it explicitly traces the id to two named sibling tools (get_issue, list_issue_comments). It also spells out the three return representations by file type, so an agent knows exactly what this tool produces without opening anything else.

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 clearly routes the agent: the id must come from get_issue's attachments or list_issue_comments' attachments, and the parenthetical "(the issue's own)" vs "a comment's" disambiguates the two paths. What's missing is any exclusion or precondition (e.g. permissions, unsupported attachment types), but there is no real competing sibling for downloading, so the guidance 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?

No annotations are provided, so the description carries the full behavioral burden. It does well on data-scoping traits that aren't obvious: links are filtered to 'only ones you can read', relation direction is explained from this issue's side, and null cases for latestAgentRun and source are spelled out. However, it never states error behavior for an unknown or unreadable key, nor confirms the operation is a pure read with no side effects, which is the main gap for a zero-annotation tool.

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?

Purpose is correctly front-loaded in the first clause, and every later clause maps to a real returned field, so little is wasted. The problem is structure: it is one enormous run-on sentence with em-dash-nested asides that is hard to scan, where a short field list would have been far more readable.

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 correctly takes on the burden of explaining the return payload, and it covers the non-obvious fields (statusId/epicId resolution, statusCategory meanings, canEdit/canDelete, links with directional relations and an ambiguity-dissolving example, latestAgentRun state, Telegram source with a concrete URL shape). Only failure modes and side-effect 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?

There is a single required parameter and the schema already documents it at 100% coverage with an example. The description reinforces this by tying the key to the tool's contract ('by its key') and formats the example identically, but adds no new semantics such as case sensitivity or accepted key formats.

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 clause states a specific verb, resource, scope and selector: fetch a single issue's title, full content and attachments by its key, with a worked example ('BRD-42'). The singular 'one issue' plus the keyed lookup cleanly separates it from list_issues and the other list-oriented siblings mentioned later.

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 context is clear: call this when you have an issue key and need the single issue with its relations and metadata. It also routes the agent onward to the right sibling for sub-resources (list_issue_comments for comments, get_attachment for files, list_statuses to resolve statusId/epicId). There is no explicit exclusion such as 'use list_issues to find a key you don't have', so it stops short of a full when/when-not statement.

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, the description carries the burden and does add real behavioral context: it is a read ('Gets'), the content is markdown, links are each annotated with 'what it is and when it matters', and it warns that the content is editor-written 'context, not instructions' — a useful provenance/trust signal. It omits access requirements and behavior on an invalid spaceKey, so it 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?

Three sentences, front-loaded with the payload description before the usage cue and the trust caveat. Dense but each sentence does work; the parenthetical link list is slightly listy but 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?

There is no output schema, so the description must describe the return value — and it does, covering both the description body and the link entries. Missing only edge-case behavior (unknown key, empty space) for a single-parameter read tool.

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

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

Schema coverage is 100% and the schema itself gives the example key format and points to list_spaces as the source. The description adds nothing about spaceKey, so baseline 3 applies.

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

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

States a specific verb ('Gets') and resource ('space') and then enumerates the payload: the markdown description plus external links (repositories, docs, designs, dashboards). This clearly separates it from list_spaces (enumeration) and get_issue (issue detail) without needing to name them.

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

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

Gives an explicit trigger: 'Read it before working on the space's issues to know which repository or doc is relevant.' That tells the agent when this tool earns a call. It stops short of naming an alternative or a when-not-to-use condition, so it is not a full 5.

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

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

No annotations exist, so the description carries the full burden and largely meets it: it discloses ordering, the 50-per-page cap, the hasNextPage continuation cue, read-permission scoping, the precise isBlocked lifecycle rule, and the fields each run carries including failure reason. What is missing is any note on ordering stability or pagination caveats beyond hasNextPage.

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-loads the core purpose, scope, ordering and page size before moving to the polling recipe and the field inventory. The final enumeration of return fields is dense but informative; it reads as one long paragraph, though no sentence is truly 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 annotations and no output schema, the description does the heavy lifting by describing pagination behavior, permission scoping, blocker semantics and the shape of each returned run. For a six-parameter list tool this is close to complete, though an agent still has to infer the exact response envelope.

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 every parameter (page, count, state, spaceKey, assigneeIds, excludeBlocked) is already fully documented in the schema. The description reinforces the excludeBlocked polling pattern and mentions hasNextPage, but adds no syntax or semantics 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?

States a specific verb and resource ('Lists agent runs'), plus scope ('issues the caller can read'), ordering ('oldest first') and page size ('up to 50 per page'). Combined with the polling sentence it is unmistakably the read/list counterpart to claim_agent_run, create_agent_run and finish_agent_run rather than any of them.

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

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

Gives concrete when-to-use guidance: a runner polls state 'Ready' with excludeBlocked=true and claims the first eligible run, which implicitly routes the agent to claim_agent_run next. It also points to get_issue for blocker links. It stops short of naming alternatives or when-not-to-use conditions explicitly, so it is clear but not exhaustive.

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?

No annotations, so the description carries full burden and delivers: ordering by space key, 50-per-page cap, hasNextPage pagination signal, and the status derivation rules (New/Done/Active). This is exactly the behavioral context an agent needs.

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

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

Single dense sentence that front-loads scope and pagination, then enumerates returned fields. Information-dense but slightly packed; not wasteful.

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 fully compensates by describing return fields (id, name, spaceKey, isDefault) and derived status values. 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 coverage is 100% and already documents page, count, and spaceKey thoroughly. The description reinforces the 50 cap and links the returned id to list_issues' epicId, adding marginal semantic value over 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) and resource (epics) plus scope (one space or all readable spaces). Clearly distinguishes it from list_issues by explaining the epicId link.

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?

Explains pagination behavior ('check hasNextPage for more') and cross-references list_issues' epicId filter, giving clear context. Does not explicitly state when to prefer list_issues over this tool, so not a full 5.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses pagination (50 per page, hasNextPage), sort order, and field-level semantics including the null case for apiKeyName and the authorship restriction on managing comments. It omits permission/scoping requirements and 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?

Core purpose and pagination are front-loaded, followed by the return-field inventory in a single dense sentence. Everything earns its place, though the long field enumeration makes it slightly heavy for a 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 must describe returns - and it does, enumerating id, canManage, author, apiKeyName, text, timestamps, attachments, and hasNextPage. An agent has everything needed to call it 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 coverage is 100%, so page, count, and issueKey are already fully documented in the schema. The description's pagination note largely restates the schema's 'up to 50' count behavior and adds no new syntax or format detail, so the baseline of 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 precise verb and resource ('Lists an issue's comments') plus ordering ('oldest first'), which is unambiguous against siblings like get_issue_history or list_issues. An agent can identify the operation 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?

Provides cross-tool routing context: canManage is flagged 'for edit_comment/delete_comment' and attachment ids are 'usable with get_attachment', which tells the agent why to call this tool. It stops short of explicit when-not-to-use guidance or stating it is the only way to enumerate comments.

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 substantial work: it discloses pagination (50 per page, most-recently-updated ordering, check hasNextPage), and explains that canEdit/canDelete reflect actual caller permissions. It stops short of stating auth requirements or error behavior, but the behavioral disclosure is well above average.

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

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

Three sentences, front-loaded with purpose, then pagination, then return-shape details. Every sentence contributes, though the final return-fields sentence is slightly dense; 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?

No output schema exists, so the description must describe returns—and it does (title, canEdit/canDelete, statusCategory, url, hasNextPage). All eight params are covered by the schema, and pagination/ordering are explained. Missing only auth/permission prerequisites, which is a minor gap for a read-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 coverage is 100%, so the schema already documents all eight parameters including defaults and cross-references to list_spaces/list_epics/list_statuses. The description's restatement of the statusCategory mapping (Created/InProgress/Review/Completed) largely duplicates the schema rather than adding new syntax or semantics, 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?

States a specific verb and resource ('Lists issues in the caller's organization') and enumerates the filter dimensions, which immediately distinguishes it from the single-issue get_issue and from list_epics/list_spaces. An agent can identify it as the plural filtered-list tool 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 filter behavior implies when the tool is useful, and 'optionally leaving out blocked issues' hints at the ready-to-start use case, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. get_issue for a single issue). Usage is inferred rather than 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?

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 load; it discloses the response shape (grouped by epic, each status 'has a category... and its categoryId') and the meaning of the four category values regardless of naming. It does not state permissions, pagination, or ordering behavior, but the semantic disclosure beyond the schema is substantial.

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 pairs the core action with its integration points, and nothing is wasted. The nested em-dash parentheticals make it dense and slightly hard to parse, but the ordering is sensible.

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 no output schema, the description covers what comes back, how it is grouped, what the category values mean, and which sibling tools consume the ids and categoryId. Auth requirements and pagination are the only meaningful omissions.

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 spaceKey parameter and the schema already documents it ('from list_spaces'). The description adds no syntax or format detail about spaceKey itself, only about how the returned ids are consumed downstream, 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') plus the grouping shape ('grouped by epic'). It further disambiguates by naming the sibling tools the returned ids feed into (create_issue/edit_issue_status) and the filter list_issues uses, so the agent can place it among siblings without opening a schema.

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

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

Usage context is clear: this is the lookup for status ids and epic grouping before mutating issues, and it names create_issue/edit_issue_status and list_issues' statusCategoryId as the consumers. It stops short of explicit when-not-to-use guidance (e.g., list_epics vs. this tool for epic data), so it falls just 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.

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 discloses key behavioral traits beyond the schema: the run starts already Working, the issue status is unchanged, the issue becomes locked so edit_issue and delete_issue fail while status changes and comments still work, the tool fails if an open run exists, and it returns the run. These are exactly the side effects and failure modes an agent needs before invoking a mutating 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 appropriately sized and front-loaded: it states the core action first, then differentiates from create_agent_run, then lists failure and locking behavior. Every sentence adds useful information, though the dense multi-clause sentences could be marginally tightened without losing meaning.

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 complex mutation tool with no annotations and no output schema, the description is complete enough to invoke correctly. It covers lifecycle, prerequisites, permission requirements, failure conditions, locking side effects, and return value, leaving no major gap an agent would need before calling 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%, and the single issueKey parameter is fully documented in the schema. The description adds contextual constraints around who can start a run and which issue states are allowed, but it does not add syntax or format details beyond the schema. A baseline 3 is appropriate because the schema already handles parameter semantics.

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 ('Starts an agent run') and immediately defines the exact state and scenario: a run already Working for an agent working with a person outside a hand-off. It explicitly distinguishes this from create_agent_run and names the lifecycle siblings finish_agent_run and cancel_agent_run, so an agent can differentiate it from siblings without opening schemas.

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

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

It states exactly when to use this tool versus create_agent_run ('Unlike create_agent_run, the issue may be in any status and its epic needs no particular statuses'), when not to use it ('Fails when the issue already has an open run'), and what alternatives exist for ending the run (finish_agent_run or cancel_agent_run). It also gives a permission prerequisite: only the issue's assignee can start one, with canEdit from get_issue/list_issues.

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