Kaiku

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

With no annotations provided, the description carries the full burden and delivers: discloses the replace-rather-than-duplicate idempotency behavior, the permission requirement (edit issues), the return value (download URL), and that mimeType is never used to serve the file. All beyond what any annotation would give.

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 several sentences but every one earns its place — idempotency, alternative routing, permission, and return value. Slightly long, but the density of useful guidance justifies the length.

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 tool with 5 parameters, no annotations, and no output schema, the description covers the return value, permissions, edge cases (data URL unwrapping, replace behavior, MIME serving), and the alternative tool. Nothing an agent needs to call 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?

Schema coverage is 100%, but the description adds meaning beyond the schema: contentBase64 accepts data URLs and unwraps them, text is stored as UTF-8, passing both is refused, and filename directory parts are dropped. It enriches every parameter's 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?

States a specific verb and resource ('Attach a file to an issue') and distinguishes from the sibling add_wiki_attachment by making the target resource clear. The opening clause leaves no ambiguity about what the tool does.

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

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

Explicitly explains when to pass text vs contentBase64, and proactively routes local disk files to the pm-files MCP server via local_files_setup, naming a concrete alternative and exclusion condition. This is model usage guidance.

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

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

With no annotations, the description thoroughly discloses side effects: notifications to authors, permission requirements, mention behavior (unresolvedMentions with reasons), agent invocation, and return fields (notified, answered, unresolvedMentions). It even details edge cases like wrong handles being stored, going well beyond basic write behavior.

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 long but information-dense, front-loading the core action and reply behavior. It trades conciseness for completeness, which is justified given the complex return semantics. No filler; every sentence contributes, though it could be tightened.

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's complexity (mentions, notifications, agent calls) and lack of output schema, the description fully covers what an agent needs: return fields, error cases (unresolvedMentions), and permission prerequisites. No significant gaps.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds context for replyTo (notifies author) and body (mentions format), but these are somewhat redundant with the schema. Baseline 3 is appropriate as the description complements but does not heavily augment 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?

The description clearly states the action (add a comment to an issue) and the optional reply behavior via 'replyTo'. It distinguishes from siblings like update_comment and add_wiki_comment by focusing on issue comments and reply semantics. The resource (issue comment) is specific and 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 explains the reply use case (replying to a comment) and notes that replies notify the answered author. It implies when not to use (e.g., for wiki comments use add_wiki_comment) but does not explicitly name alternatives or exclusions. Context is clear for a comment tool.

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

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

With no annotations provided, the description carries full behavioral burden and does so thoroughly: re-attaching replaces bytes and bumps version, retries cannot duplicate, the attachment is not on the page until referenced, the response supplies Markdown for update_wiki_page, and dark-theme naming is explained. This is rich, non-obvious behavior disclosure.

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

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

The description is longer than average but every sentence earns its place: identification, content modes, idempotency, local-file routing, page-reference requirement, dark-theme pairing, and permissions. It is front-loaded with the core action and identifier options before behavioral caveats.

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 8-parameter tool with no annotations and no output schema, the description is complete. It covers how to identify the page, how to supply content, what happens on re-attach, what the response provides, dark-theme conventions, and permissions. 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?

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already documents about 'text' vs 'contentBase64', 'filename' directory stripping, and 'mimeType' being ignored when bytes self-identify. It adds no meaningful parameter semantics beyond the schema, which is acceptable given full 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 opens with a specific verb and resource: "Attach a file to a wiki page," and immediately clarifies page identification via 'pageId' or 'spaceKey' + 'title'. It also distinguishes content delivery modes (base64 vs text), making the tool's scope unmistakable even alongside the sibling add_attachment.

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 explicit usage guidance: use 'text' for text files, use 'contentBase64' for bytes, and route local on-disk files to the pm-files MCP server instead. It also notes the permission requirement. It does not explicitly contrast this tool with the sibling add_attachment, but the context is otherwise clear.

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 full responsibility for behavioral disclosure, and it succeeds: it explains reply notification semantics, mention handling, permission requirements, and the exact response fields including the unresolvedMentions edge case. This goes well beyond a basic 'comment on a page' statement.

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 long but information-dense, and it front-loads the core action before diving into notification, identification, and response details. Every clause covers a question an agent would need answered, though the dense single-paragraph structure could be slightly more scannable.

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

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

For a tool with five parameters, no annotations, and no output schema, the description is remarkably complete: it covers page identification, reply semantics, permissions, Markdown rendering, mention syntax, and all response fields. An agent has everything needed to call this tool correctly 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?

Schema coverage is 100%, so the baseline is 3. The description adds real value by explaining the reply notification behavior tied to replyTo, the mention syntax, and why unresolvedMentions is important. Some redundancy with schema descriptions exists, but the description still enriches the parameters.

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

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

The description opens with the precise action 'Comment on a wiki page, or reply to one of its comments', naming both the resource and the key alternative behavior. It is clearly distinct from generic add_comment and other wiki tools because it centers on commenting and replying to existing 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?

It gives concrete usage context: how to identify the page, when replyTo applies, what permission is needed, and how mentions are formatted. It does not explicitly say 'use add_comment for non-wiki comments', so it lacks an explicit exclusion of alternatives, but the intended situations are clear.

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 of behavioral disclosure, and it does so well. It explains that this returns rather than modifies data, clarifies the subtle meaning of 'offered' versus 'enabled,' notes that issued bills carry a frozen copy unaffected by this call, and states that amounts are always USD regardless of account currency. These are genuine behavioral insights beyond a generic read-only hint.

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 dense but mostly purposeful, front-loading the administrator scope and topic before diving into details. It includes a ticket reference (PM-625) that adds little functional value, but every other sentence contributes meaningful distinctions such as the 'offered' flag semantics, frozen bill copies, and USD normalization.

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

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

For a zero-parameter read tool with no output schema and no annotations, the description is quite complete. It enumerates the returned fields, explains the key flag nuance, addresses the impact on existing bills, and clarifies currency behavior. It could be improved by naming the corresponding sibling admin_set_bank_transfer for the update path, but nothing essential is missing for invoking this 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?

The tool has zero parameters and the schema description coverage is 100%, so the schema already handles all input semantics. The description adds relevant context about the data returned, but there are no parameters for it to explain. A 4 is appropriate given the no-parameter baseline.

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 identifies the resource—bank transfer destination details—and implies a read operation through phrases like 'what this returns.' It lacks an explicit verb such as 'get' or 'list,' but the meaning is not vague and the information enumerated makes the purpose clear. It does not explicitly differentiate from the sibling admin_set_bank_transfer, but the read-only nature is strongly implied.

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

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

The description states 'Administrators only,' which gives access context, and warns that bills already issued are not affected by this tool. However, it does not explicitly say when to prefer this over admin_set_bank_transfer or mention the write alternative. The usage context is implied rather than directly 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 burden. It discloses important behavior: null counts with a reason rather than zeros for unresponsive projects, week-over-week comparisons, and admin-only access. It doesn't mention side effects or exact auth requirements, but the tool is clearly a read-only report.

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 audience and topic. The long list of metric types is dense but meaningful. The final sentence about weeksAgo is slightly redundant with the schema, but 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, the description lists the major output facets and the critical null-vs-zero behavior. The only parameter is documented in the schema. It doesn't define the exact response shape, but there is enough information for an agent to decide when to call it and what to expect.

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 describes weeksAgo fully, including '0 is the last full week, 1 the one before it.' The description only says 'Ask for an earlier week with weeksAgo,' which adds no new semantic value beyond the schema. Baseline 3 is appropriate given 100% schema 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 what the tool reports: the error collector's week with events, distinct errors, week-over-week comparisons, first-seen errors, loudest errors, and regressions. It doesn't use an explicit verb like 'get' or 'list', and it doesn't name sibling tools, but the error-report focus is distinct enough to separate it from admin_landing_week and admin_overview.

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 clear context: administrators only, the same numbers as the weekly error report, and how to request earlier weeks via weeksAgo. It doesn't explicitly state when not to use it or name alternatives, but the context is strong enough for an agent to know when this is the right reporting tool.

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

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

With no annotations present, the description carries the full burden and delivers extensively: it discloses that 'stock' and 'revenue' must not be added together, that totals are only as fresh as the fleet's newest machine copy ('a machine that is behind makes the totals older than they look'), that AI totals are null rather than zero until machines report, and that 'ai' is excluded from both stock and revenue. This goes far beyond anything the schema or annotations reveal.

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 content is valuable but delivered as one dense, run-on paragraph: money semantics, machine freshness, activation, and AI accounting are all jammed together without separation. It is far longer than typical tool descriptions, and its structure makes critical caveats — null-never-zero and don't-add-stock-and-revenue — easy to miss, even though 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 complex report tool with no output schema and no annotations, the description is remarkably complete: it names and defines the key fields ('stock', 'revenue', 'machines', 'activation', 'ai', 'ai.missing', 'ai.reported') and their semantics, plus staleness and currency behavior. It falls short only in lacking a crisp overall response-shape summary and in risking misreading due to its dense, unstructured prose.

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% — 'to', 'days', and 'from' each carry a description including defaults and behavior. The description only reinforces this with 'Default period: the last 90 days,' which mirrors the schema's days default rather than extending it, so the baseline 3 for high schema coverage 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 clear purpose: an administrator-only view of the installation's business metrics — 'registrations, how many of them became working companies, purchases and conversion by cohort, churn, and money.' It identifies both the resource (the business/funnel report) and period scoping. It lacks an explicit verb ('reports'/'returns' is implied) and never names a sibling to distinguish from, so it stops short of 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 'Administrators only' prefix gives an access-level precondition, and the detailed metric list lets an agent match queries about registrations, churn, or revenue to this tool. However, it never explicitly routes to or away from overlapping siblings such as admin_overview, admin_invoices, or admin_landing_week — differentiation is left entirely to inference.

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

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

With no annotations provided, the description fully carries the behavioral burden and does so thoroughly: it discloses the access restriction, that amounts are never aggregated across currencies, that the 'machines' field indicates ledger currency/staleness, and that missing delivery records are reported as missing rather than as empty lists. These are non-obvious, high-value behaviors an agent must know to interpret results 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?

The description is dense at roughly five sentences, but every sentence earns its place given the absence of annotations and an output schema — each covers a real interpretation hazard (currency separation, staleness, missing-data semantics). The purpose is front-loaded in the first sentence, though a couple of caveats could be tightened.

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 compensates by describing the return shape in prose (per-invoice fields, currency handling, machines staleness indicator, delivery-record semantics). Parameters are fully covered by the schema. The description is close to complete for a list tool; only minor details like exact row ordering or error behavior are left to 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 the schema already documents slug, limit, and status precisely (address filter, row count with default/max, and state filter with examples). The description adds no parameter-level meaning beyond the schema, 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 clearly identifies the resource (invoices) and the operation (listing what companies were asked to pay and what was paid), enumerating the output fields: amount, coin, paid state, short amount, and payments. It does not state an explicit verb like 'list' and does not name a sibling, but no other sibling tool covers invoices, so confusion is unlikely.

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 'Administrators only' prefix provides a clear access prerequisite, and describing the list as 'the fleet's ledger' implies it is the authoritative invoice view. However, there is no explicit when-to-use versus alternatives, no exclusions, and no mention of filtering strategy beyond what the schema's status/slug parameters imply.

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 burden and discloses an access restriction, the weeksAgo offset behavior, and the fact that only figures are returned rather than the rendered message. It does not explicitly say read-only, but the semantics strongly imply a non-mutating report query.

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 compact sentences each add distinct value: audience and scope, relationship to the weekly report, and the behavior of the request/response. 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?

For a tool with one optional parameter and no output schema, this description is complete: it lists the returned metrics, notes what is not returned, states who may use it, and explains how to select earlier weeks. No critical calling information 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?

The only parameter, weeksAgo, is fully covered by the schema, including the 0/1 week semantics. The description merely reinforces that earlier weeks are requested with weeksAgo, adding no real detail beyond the schema, 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?

The description clearly identifies an administrator-only view of the landing site's weekly metrics and enumerates the specific figures: visits, referrers, sign-up clicks, and registrations. It is distinguishable from admin siblings by its narrow focus on the landing site week, though it lacks an explicit verb like 'get'.

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 explicitly restricts usage to administrators, connects the output to the weekly monitoring-chat report, and instructs the caller to use weeksAgo for earlier weeks. It does not mention alternative tools or when not to use it, but the context is clear enough for this single-purpose query.

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 well: it warns about administrator-only access, notes that costs are estimates, explains that load is measured 'against allowed, where an allowance is known', and explicitly says 'Who spent it is not returned here'.

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 front-loaded with the purpose and access restriction, then adds only load-bearing detail: metric list, breakdown dimensions, estimate caveat, and exclusion. Every sentence earns its place and there is 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 one-parameter read-only admin tool with no output schema, the description fully orients the agent: what is measured, what is estimated, what is excluded, and how cost is broken down. Nothing needed for 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?

The schema already provides 100% coverage for the single `days` parameter, including default and the 0-means-all-time special case. The description adds context about rolling windows and breakdowns but does not need to duplicate the 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 immediately states the resource: machine load and language-model spend, with explicit scoping ('this machine's own', 'model spend covers the assistant, search-by-sentence and translation'). It distinguishes itself from other admin tools by clarifying that individual spend attribution is not included.

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 marks the tool as administrator-only and defines what data it covers, which gives an agent context for when to call it. However, it does not explicitly name sibling alternatives like admin_overview or state when one should be preferred over the other.

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 of behavioral disclosure, and it excels: it explains that totals are null rather than zero when a machine did not answer, defines the 'fleet' and 'here' fields, and clarifies that breakdowns reflect only this machine's data. It also gives an interpretive rule: read null as 'nobody knows', never as 'none'. This goes well beyond a generic overview description.

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 front-loaded with the key purpose and audience, and every sentence adds meaningful semantic detail about scope and null handling. It is somewhat dense and longer than strictly necessary, but no sentence is 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?

Given there is no output schema, the description adequately explains what the tool returns: the installation-wide counts, the issue breakdowns, and the fleet/here distinction. It also covers the critical null semantics, so an agent can interpret results correctly without needing an output 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?

The tool has zero parameters and the schema is an empty object with 100% coverage, so there is no parameter burden for the description to carry. A baseline of 4 is appropriate since the description correctly omits any parameter explanations.

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

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

The description states a specific verb and resource: an administrative overview of the whole installation, enumerating accounts, workspaces, projects, issues, comments, sprints, and issue breakdowns. It explicitly differentiates itself from company-scoped views by emphasizing 'across every workspace' as 'the installation's rather than one company's.' This makes it clearly distinguishable from sibling admin tools such as admin_workspaces.

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: it is restricted to administrators and is meant for installation-wide counts, not a single company's data. It does not explicitly name alternative tools or state when not to use it, but the scope and audience are clear enough for an agent to route 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 disclosure burden and delivers: admin-only auth, mutation ('this one CHANGES things'), whole-set overwrite semantics, audit attribution ('recorded against the calling administrator'), and the guarantee that already-issued bills keep their details. The clarification that minimumUsd floors the method rather than the debt prevents a likely misunderstanding. No contradiction with annotations (none provided).

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 dense but disciplined paragraph: it opens with the two most critical facts (admin-only, mutating) and every subsequent sentence carries a distinct behavioral rule with a rationale. No filler despite covering roughly eight distinct semantics for a 13-parameter tool.

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

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

For a high-complexity, no-annotation mutation tool without an output schema, the description covers auth, side effects, failure modes, and persistence semantics thoroughly. It loses a point for the unresolved daysToArrive retention exception and for not stating the response shape, though the latter matters little for a setter.

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 field descriptions are already rich, so the description's main addition is the cross-cutting rule that every omitted parameter is cleared — the single most dangerous invocation trap. However, that absolute rule sits in tension with the schema's daysToArrive note that 'Left out, the stored number is kept,' which an agent could not resolve confidently.

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

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

The description states a specific verb and resource — 'state where bank transfers are to be sent' — and immediately flags it as the mutating counterpart to the read tool by instructing 'Read admin_bank_transfer first.' It is unmistakable what this tool does and how it differs from its sibling.

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

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

Explicit workflow guidance: 'Read admin_bank_transfer first and repeat what you are not changing' names the alternative tool and the precondition for use. It also spells out exactly when the operation is refused (enabling with missing required fields, with the refusing field named) and when it is never refused (disabling), leaving nothing 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?

With no annotations provided, the description carries the full behavioral burden, and it does so well: it discloses the administrator-only restriction, newest-first ordering, the hundred-entry cap, the presence of a reason and a named actor, and the cross-machine exclusion. It stops short of explicitly stating that the operation is read-only, though the journal/report framing strongly implies it.

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 front-loaded with the core purpose and audience, then expands with use-case and exclusion details. It is somewhat elaborate, but every sentence contributes meaning—order, cap, reason field, actor rationale, and machine caveat—so it earns a high score without being maximally terse.

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 is remarkably complete: it specifies who may call it, what kind of entries appear, the ordering, the maximum number of entries, the presence of reasons and actor names, and an important data-scope limitation. An agent has enough context to invoke it correctly 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?

Schema coverage is 100%: the slug parameter already has a helpful description ('The company's address — acme in acme.kaiku.tech'). The tool description reinforces that the slug identifies the company and alludes to scope boundaries, but adds no significant new parameter-level semantics beyond the schema, 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 description clearly defines the tool as an administrative journal: 'what was done to one company and by whom' with an explicit list of recorded events (created, plan changed, period extended, credited, suspended, resumed, erased). It distinguishes this from broader admin tools by scoping to a single company and emphasizing the audit/reason aspect, making its purpose unmistakable.

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 an explicit use case: 'This is the answer to why is this company on a period nobody paid for', and also states when it does not apply: 'A company living on another machine of the fleet is not here'. It does not name a specific sibling tool as an alternative, but the when/when-not guidance is clear enough to route an agent 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 provided, the description carries the full behavioral burden and handles it well. It discloses that this is a statistics surface, explains that null meter readings indicate the machine was not asked rather than being idle, notes that owners are omitted unless withOwners is true, and guarantees an e-mail address is never returned.

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

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

The description is dense and front-loaded with the core purpose, and every sentence adds operational value. It is longer than strictly necessary and packs several caveats into successive sentences, but nothing important is missing and the structure is coherent.

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

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

For a tool with no output schema, the description covers an impressive amount: auth requirement, row contents, filter motivation, null semantics, owner handling, and privacy guarantees. It does not describe pagination, exact response shape, or error behavior, but for an admin statistics surface those are minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description restates withOwners behavior and adds a use-case for endingInDays, but it does not add new parameter meaning, syntax, or constraints beyond what the schema provides. 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 clearly identifies the resource — every company on the installation — and lists the substantive fields returned (plan, state, expiration, usage, balance). It does not use an explicit verb like 'list' or 'get', and it does not explicitly distinguish itself from sibling admin tools, so it stops just short of a 5.

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

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

It states 'Administrators only' and gives a concrete usage pattern ('Ask with endingInDays to get only the ones running out that soon, which is how

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 fully discloses side effects: re-answering changes the answer and notes it in the thread, deadline-expired answers replace the prior outcome, the answer is written as an ordinary comment, and the asker is notified. This is rich, honest behavioral detail.

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

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

Four sentences, each carrying meaningful information (action, permission, deadline behavior, thread/notification effect). No fluff, but slightly longer than necessary; still well-structured and front-loaded.

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

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

For a tool with 3 params and no output schema, the description covers the core behaviors: who can call, effects of re-answering, deadline handling, and how the result is recorded. It omits error cases (e.g., unauthorized attempts), but that is acceptable 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 coverage is 100%, and each parameter already has clear descriptions (option counted from 0, questionId source, note as qualification). The description adds no new parameter-level meaning beyond what the schema provides, 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 (answer) and resource (a question on an issue) and distinguishes from siblings like ask_issue_question, withdraw_issue_question, and list_issue_questions by focusing on the answering action. The purpose is unmistakable.

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 clear context: only the addressee may answer, and a past deadline does not block answering. However, it does not explicitly name alternatives or state when not to use this tool, leaving some inference needed.

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 that the question appears as an ordinary comment, is tracked separately in the Questions list, has a deadline and default option behavior, and requires comment permission. This is comprehensive, though it doesn't cover error cases or response format.

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 detailed but every sentence contributes: purpose, behavior, deadline, permission, and differentiation. It's front-loaded with the primary function and has no filler. The note about the bgs tool is valuable for disambiguation.

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 7 parameters, 4 required, and no output schema, the description covers the essential operational context: how the question appears, tracking, deadline semantics, default option, and permission. It's sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for defaultOption (safe assumption) and ttlHours (default 48 hours), which are not fully explicit in the schema, and clarifies the purpose of options. This adds meaningful value beyond the schema.

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

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

States precisely the action (ask one person a question with pre-written options) and the resource (issue thread), and distinguishes it from the bgs ask_question tool. The verb and object are unambiguous, and it differentiates from sibling add_comment by emphasizing the tracked decision aspect.

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 the primary use case (getting a decision that doesn't get lost in the comment stream) and contrasts with the bgs tool. Provides guidance on when to use defaultOption and ttlHours. However, it doesn't explicitly name alternatives like add_comment for cases where options are not needed, though the distinction is clear.

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 richly: it discloses the history line, watcher notices under the caller's name, that only the item's box is touched so concurrent description edits are safe, idempotent no-op behavior on an already-ticked item ('changed' false), and the permission requirement.

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 action and resource, and every clause adds a distinct behavioral fact. Slightly eroded by the awkward, run-on phrasing 'Written as a click on the item is:', which slows parsing.

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

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

For a 3-param mutation tool with no output schema and no annotations, the description covers return signaling ('changed' false), failure semantics, concurrency safety, side effects, and permissions — nothing an agent needs to call 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it frames 'checked' as tick/untick and documents the idempotency outcome for the checked parameter, and reinforces that 'id' comes from get_checklist.

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 ('Tick or untick') on a specific resource ('one checklist item') and identifies the source of the id via get_checklist, so it is immediately distinguishable from get_checklist and the other issue-mutation 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?

Explains the precondition (id must come from get_checklist) and the recovery path when an id resolves to nothing ('read the checklist again'), plus the required permission. It does not contrast against other mutation tools explicitly, but the context is clear enough to select 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 and does so: it discloses the readership model (token owner, 'readers', project lead, nobody else), what the response contains per mode ('readableBy', a 'form' link, or id/name but never the value), the 'dropped' failure surface with reasons, and the required edit permission. It also flags log/context leakage risk. This is unusually thorough behavioural disclosure.

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

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

The critical scoping (what it does, then the form-vs-stored distinction) is front-loaded, and every sentence is load-bearing. It is nonetheless dense and long for a 5-parameter tool, with the 'do not repeat the value' warning restated, which slightly dilutes the signal.

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 still tells the agent what comes back in each mode, what failure looks like ('dropped'), and the permission prerequisite. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: the mutual mode switch between 'value' present vs absent, the issueKey-or-pageId attachment target, the comma-separated readers format referencing list_users, and the constraint that 'name' must not contain any part of the value. It stops short of documenting every edge case, so not a 5.

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 sentence names a specific verb+resource (attach a secret to an issue or wiki page) and immediately contrasts it with the sibling behaviour it replaces (writing secrets in comments/descriptions). An agent can distinguish it from add_comment, update_credential, and reveal_credential 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?

It states when to use this tool versus the alternative (instead of a comment/description), when to pass issueKey vs pageId, and gives an explicit preference rule: omit 'value' whenever the secret is not already in the conversation. It also names the exclusion case (value that would pass through the model).

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 well: it discloses the permission requirement, the return value, and the non-obvious mention behavior ('a wrong handle is stored as written and never refused'), plus the 'notified'/'unresolvedMentions' response fields. It stops short of describing side effects like notifications being sent or rate limits.

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

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

The core action is front-loaded in the first two short sentences, and the returns/permission facts follow. The final sentence is dense and clause-heavy but every part carries real information about mention resolution, 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?

There is no output schema, so the description must explain the return shape — and it does ('new issue key', 'notified', 'unresolvedMentions'). Combined with 100% schema coverage on all 12 params, an agent has enough to invoke correctly; only the sibling routing and side-effect surface are left implicit.

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

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

Schema description coverage is 100% and each of the 12 parameters is thoroughly documented in-schema (including enums-by-example and the mention/LaTeX syntax). The description adds no parameter-level detail beyond what the schema already 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+resource ('Create an issue') with scope ('in a project visible to this token') and even names the return value ('the new issue key'). An agent can distinguish this from create_project, update_issue, and search_issues 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?

It gives preconditions ('Requires permission to create issues in that project', project must be visible) but never names when to reach for this versus update_issue or other creation siblings. Usage is implied by the verb rather than explicitly routed.

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 it succeeds: it discloses key-conflict refusal, idempotent retry behavior, key visibility in issue keys and commits, cost of renaming, absence of delete, and permission inheritance for subprojects.

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 long but every sentence carries a non-obvious behavioral consequence: permissions, key semantics, retry safety, deletion policy, and subproject leadership. It is front-loaded with the primary purpose and audience before diving into edge cases.

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 6 parameters, no annotations, and no output schema, this description is unusually complete. It covers who may call it, side effects, idempotency, conflict behavior, and subproject role inheritance — enough for an agent to invoke it correctly and anticipate outcomes.

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 substantial meaning beyond the schema: the key is never auto-invented, taken keys are refused with the naming project, the lead default carries configuration implications, and parentKey grants inherited access with the parent's roles.

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 action and resource: 'create a project — a new key, a starter board, and its own wiki space.' It clearly distinguishes this from siblings like create_project_rule and create_wiki_page by naming the full project-scope side effects.

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 explicit audience guidance ('Administrators only', parent lead for subprojects) and explains retry behavior. It does not directly name alternatives or say 'use this instead of X', but the context is clear enough for a create-project tool.

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

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

With no annotations, the description carries the full behavioral burden and does so exhaustively: journal outcomes ('alreadyThere', 'tooLong', 'moveRefused', 'moved', 'tooDeep'), the hidden marker that suppresses re-append, the identity model ('acts as whoever last saved or switched it on'), the duty access model ('runs on your behalf and access, switched off if you lose the project'), and hard limits (capUsd max 5, three-move depth).

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 core purpose is front-loaded, but the body is a single ~600-word paragraph with no headings, bullets or grouping, and several passages (trigger and action explanations) restate what the schema's parameter descriptions already say. Most sentences carry real information, but the density and lack of structure make it hard to scan.

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

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

For an 18-parameter, annotation-free tool with no output schema, the description covers triggering, actions, edge cases, permissions and failures thoroughly. The one real gap is the call's own result: it never says what create_project_rule returns (e.g. the new rule's id), which the absence of an output schema leaves undocumented.

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 per-parameter meaning is already supplied and the baseline is 3. The description adds cross-parameter semantics the schema cannot express: 'only entered has a status; pass an empty one for the others', empty template for 'move', fixed action once the rule exists, and how agentActions/agentFields/doneStatus interact for a duty.

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 names the exact verb+resource ('Add a rule to a project') and immediately states the core effect (append 'template' when an issue enters 'status'). It also names the sibling list_project_rules as the source of valid state/type names, so an agent can separate this create tool from the update/delete/list rule 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?

Usage context is unusually rich: it explains which trigger applies in which situation, when 'status' must be empty, when 'template' must be empty (action 'move'), and that only project leads/admins may call it. It does not, however, explicitly route the agent to update_project_rule for modifying an existing rule, so the create-vs-update choice is left implicit.

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 meaningful behavior: name uniqueness within a project (case-insensitive), the permission requirement, and the response shape ('as list_versions gives it'). It omits nothing critical for a create 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 purpose is front-loaded, but the middle sentence is padded with tangential parenthetical JQL examples ('fixVersion = "2.4.0"', 'fixVersion in unreleasedVersions()') that don't help invoke the tool. Useful context is diluted by verbose asides.

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 purpose, permissions, uniqueness constraints, and the return shape by reference. It is complete enough to call 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%, so the schema already documents all five parameters (name, projectKey, dates, description). The description adds the name-uniqueness constraint but no syntax or format detail beyond the schema, 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+resource ('Add a version to a project') and places it in the sequence. It explicitly distinguishes itself from siblings release_version and list_versions, so an agent can route without opening other 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?

Names the alternative for a related action ('Releasing it is release_version's') and states the prerequisite 'Project lead or admin only'. It gives clear context for when this tool applies but does not spell out 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?

With no annotations, the description carries the full behavioral burden, and it is rich: it discloses that pages hang off the space home page unless parented, that mention syntax differs from issues, that wrong mentions are stored silently, and that the response includes 'notified' and 'unresolvedMentions'. This is exactly the kind of hidden behavior an agent needs before invoking the 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?

The description is dense but every clause earns its place—parent behavior, mention syntax, link syntax, return payload, and silent-failure behavior are all useful. It is front-loaded with the core action and return values, though it could be easier to scan if split into sentences or bullets.

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 the return shape itself; it does, naming the new page id, URL, 'notified', and 'unresolvedMentions' with reasons. Combined with 100% parameter coverage, nothing critical is missing for safe and correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: the mention form that actually notifies, page-link syntax, title uniqueness, and the parentId/parentTitle alternatives. It does not simply repeat property names.

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 and resource: 'Create a wiki page from Markdown in a space you can write to.' It immediately distinguishes the operation from update/delete/comment siblings and states the object being created. It also clarifies the default placement and expected return values.

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 ('space you can write to') and explains when to use parentId versus parentTitle, including the same-space constraint. It does not explicitly name an alternative tool, but none of the siblings provides create-wiki-page functionality, so the contextual 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains side effects of both actions: release joins or opens a request and triggers the usual acknowledgement; dismiss drops files and deletes the row after 30 days. The full-write-access requirement is also 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?

The description is appropriately sized and front-loaded with the purpose. Each sentence adds useful detail, though the 'release' sentence is long and somewhat dense, containing multiple clauses that an agent must unpack.

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 mutation tool with no output schema and no annotations, the description covers the essential context: permissions, side effects, and decision semantics. It does not describe the return value or error behavior, but those are not critical for correct invocation here.

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 covers both parameters fully, including the source of letterId and the allowed decision values. The description adds meaningful nuance by explaining what 'release' and 'dismiss' actually do, which goes beyond the schema's terse 'release' or 'dismiss'.

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

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

The description names a specific verb ('decide') and resource ('held or failed letter'), and defines the two outcomes ('release' and 'dismiss') with concrete meanings. This clearly distinguishes it from sibling tools like list_support_letters and get_support_letter, which only read or list letters.

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 conditions for when each decision applies: 'release' when the letter proves it answers a request, 'dismiss' when it is not a request. It also notes the permission requirement. It does not explicitly say when not to use this tool versus alternatives, but the decision criteria are concrete enough for an agent to route 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?

No annotations are provided, so the description carries the full burden. It discloses a key prerequisite ('Requires permission to edit the issue') and clarifies the id provenance, but it does not state whether the deletion is permanent or irreversible, nor describe error behavior or success output. This is adequate but leaves some behavioral detail unspecified.

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 three sentences with no filler. The main action is front-loaded, the alternative guidance is concise, and the permission note is a single short sentence. Every word 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 simple two-parameter delete operation with full schema coverage, the description covers the core action, the alternative for corrections, and a prerequisite. It is nearly complete; the only addition might be a note on the success outcome (e.g., no return value), but that is not critical given the 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%, so the schema already documents both parameters. The description adds context that the id comes from get_agent_usage, which is helpful, but does not elaborate on parameter semantics beyond that. Baseline 3 is appropriate given the full schema 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 explicitly states the verb 'Remove' and the resource 'agent-usage record', and specifies the context 'from an issue'. It also distinguishes itself from siblings by naming the id source (get_agent_usage) and the alternative for corrections (report_agent_usage). Purpose is 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?

The description gives explicit when-to-use guidance: it says to use report_agent_usage instead for correcting numbers, and it notes the permission requirement for editing the issue. This clearly directs the agent to the right tool for the task, leaving no ambiguity.

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 must carry the behavioral burden, and it does: it discloses the operation (remove), the required permission, and the source of the identifiers. It could add more detail about permanence or error behavior, but for a straightforward delete action the core behavioral traits 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?

The description is a single efficient sentence that front-loads the action and scope, then adds the identifier alternatives, the data source, and the permission requirement. Every clause carries useful information with no wasted words.

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 delete tool with three parameters (all schema-documented), no output schema, and no nested objects, the description is nearly complete: it states the action, required permission, and identifier provenance. It lacks detail on edge cases like duplicate filenames or side effects, but these are not critical for invoking the tool 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?

The schema already documents all three parameters with 100% coverage, providing descriptions for id, key, and filename. The tool description adds the useful note that both id and filename come from get_issue, but this is a minor enhancement over the schema, not a necessary compensation.

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 ('Remove'), names the resource ('a file from an issue'), and clearly distinguishes from siblings like delete_wiki_attachment by specifying the issue contextasi. It also clarifies the two acceptable identifiers (filename or attachment id), making the tool's scope unmistakable.

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 clear context by stating it requires permission to edit issues, and indicates that the filename/id should come from get_issue, implying the tool should be used after fetching issue details. However, it does not explicitly mention when not to use it or name alternatives (e.g., delete_wiki_attachment for wiki attachments), so it stops 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?

With no annotations, the description carries the full burden and does it well: it discloses the destructive scope (value, reader list, and the read-record are all removed), that the action is irreversible ('cannot be brought back'), and the authorization requirement (attacher or project lead). These are exactly the traits an agent needs before invoking a destructive 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?

The verb+resource and the destructive cascade are front-loaded, followed by the permission constraint and the routing hint. Every clause adds actionable information; none is 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 one-parameter destructive tool with no output schema and no annotations, the description covers effect, cascading side effects, reversibility, authorization, and the safer alternative. Nothing essential for 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% and the single parameter already documents 'Credential id, from list_credentials.' The description repeats that provenance without adding format, range, or lookup detail beyond the schema, 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 (Remove) and resource (credential), and pins the identifier source to list_credentials. It also distinguishes itself from the sibling update_credential, so an agent can separate it from related credential tools without reading 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 alternative and the condition that selects it: revoking a single person's access should go through update_credential's 'readers' rather than this destructive tool. It also states who is permitted to invoke it, which is real usage guidance, not just context.

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

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

No annotations are provided, so the description carries the full burden. It clearly states that the operation is destructive (removes a column), explains the side effect on issues (they lose a value), and clarifies that issues themselves are untouched – providing rich behavioral context beyond the simple 'remove' action.

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 compact and front-loaded with the core action. Every sentence adds value: the first states the action, the second explains the consequence, and the third adds the permission constraint. No wasted words.

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 straightforward mutation tool with two parameters and high schema coverage, the description covers the essential context: action, side effect, and authorization. It could mention error responses or whether the operation is reversible, but these are minor 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?

The input schema already has 100% description coverage, with clear examples for 'name' and 'projectKey'. The description does not add new parameter-level details but reinforces the semantic that 'name' refers to a column (field) name. Given high schema coverage, a score 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 description clearly states the verb ('Remove') and resource ('a column from a project'), and it distinguishes itself from siblings like 'set_project_field' which likely modifies rather than deletes. The phrasing is specific and 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 explicitly notes the permission requirement ('Project lead or admin only'), which serves as a strong usage constraint. It also implicitly distinguishes from 'list_project_fields' (which lists) and 'set_project_field' (which modifies), making it clear when to use 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?

No annotations are provided, so the description carries the full burden. It discloses the refusal conditions (issues/fields referencing it), the cascading behavior ('a rule on it goes with it'), and the permission requirement. This is strong behavioral disclosure, though it doesn't detail the exact error response 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?

Three sentences, each earning its place: the action, the refusal conditions, and the permission requirement. Front-loaded with the verb and resource, 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 2-parameter tool with no output schema, the description covers the action, prerequisites, refusal conditions, and permissions. It doesn't describe the return value or error format, but that's minor given the simplicity and the strong behavioral disclosure.

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 both parameters ('name' and 'projectKey'). The description adds context about the 'own type' but doesn't add new parameter-level meaning beyond the schema. 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 action ('Remove an issue type of this project's own') and the resource (project issue type). It distinguishes itself from siblings like set_project_issue_type and delete_project_field by specifying 'own' issue type and the deletion context.

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 explicitly states when NOT to use it: 'Refused while any issue is of it or any field is kept for it — change those first'. It also names the required permission ('Project lead or admin only'), giving clear usage context and prerequisites.

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

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

With no annotations provided, the description carries the full disclosure burden. It surfaces two important side effects (added checklists remain in issues; the journal is deleted) and the authorization requirement, and implicitly conveys permanence by contrasting deletion with temporary disablement.

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 compact and front-loaded: the core action, key side effects, the alternative, and the permission constraint all fit into a few short sentences. Every clause earns its place, with 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?

For a simple two-parameter deletion tool with no output schema and no annotations, the description is complete: it covers the action, parameter origin, side effects, alternatives, and access control. Nothing material is missing for an agent to 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?

The input schema already provides 100% description coverage for both parameters. The description reinforces that id comes from list_project_rules, but that duplicates the schema's own parameter description rather than adding new semantic value.

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 ('Remove') and a precise resource ('a project rule'), and ties the identifier to list_project_rules. This clearly differentiates the tool from its closest sibling update_project_rule and from other deletion 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?

It explicitly directs agents to update_project_rule with enabled=false for the temporary-disable use case, and states the permission boundary ('Project lead or admin only'). This tells an agent exactly when to choose this tool versus the alternative.

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 must disclose behavior. It does so well: mentions that references in the page body are left alone and stop resolving, and that edit permission is required. This covers the key side effects beyond the deletion itself. It doesn't discuss reversibility or error cases, but for a delete operation 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 two sentences, front-loaded with the core action and identification method, followed by a side-effect warning and a permission note. Every sentence carries essential information with zero filler. Excellent structure.

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

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

For a mutation tool with no output schema and no annotations, the description covers the essential elements: what it deletes, how to identify the target, what side effects occur (references left behind), and what permission is needed. 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?

Schema description coverage is 100%, so the schema already documents each parameter. The description adds value by clarifying the relationship between pageId and spaceKey+title (two identification modes) and by specifying that filename comes from get_wiki_page. This goes beyond the schema's individual field descriptions, so it earns a 4.

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 ('Remove'), a precise resource ('a file from a wiki page'), and the exact identification method ('by its filename as listed by get_wiki_page'). It clearly distinguishes from sibling tools like delete_attachment (generic) and get_wiki_attachment (retrieval). No ambiguity.

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 clear identification instructions ('by pageId, or by spaceKey + title') and notes the permission requirement. It doesn't explicitly compare to alternative delete tools, but the context makes the target clear. The guidance to tidy the body if it referenced the file is a useful usage hint. Slightly less explicit than naming an alternative, so a 4.

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 of disclosing behavior. It thoroughly explains the destructive nature, the subtree deletion behavior with refusal unless includeChildren is set, the unconditional protection of the home page, and the permission requirement. It even notes that the response will list what would be deleted, which is valuable operational context.

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

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

The description is concise — four sentences that front-load the purpose, then cover identification, the critical subtree caveat, the home-page exception, and the permission requirement. There is no redundant or filler text; every sentence 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 destructive tool with no output schema, the description covers all necessary aspects: what it does, how to identify the target, the main risk (children), the required flag, an absolute restriction (home page), and the permission prerequisite. An agent has everything needed to decide whether and how 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?

Although the schema descriptions already cover each parameter at 100%, the description adds meaningful interplay between them: the mutual exclusivity of id vs. title+spaceKey, and the consequence of includeChildren (deletes descendants but requires explicit opt-in). This goes beyond the isolated schema descriptions and clarifies how to combine parameters correctly.

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 starts with the clear verb-resource pair 'Delete a wiki page' and immediately specifies the two identification methods ('id' or 'spaceKey'+'title'). This is unambiguous and distinguishes it from sibling tools like update_wiki_page or get_wiki_page. The inclusion of key constraints (children, home page, permission) further anchors 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 implicitly defines when to use it: when you need to permanently remove a wiki page. It provides operational constraints (requires edit permission, home page never deletable, children subtree refusal unless includeChildren=true) that guide correct usage. It does not explicitly name alternative tools for non-destructive actions, but for a delete operation this is not a major gap.

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 behavioral disclosure burden. It goes beyond a generic get by explaining that null metrics mean 'nobody reported it' rather than zero, and that a 'reporting' field counts records carrying each metric. It also clarifies that results can cover local or mirrored/upstream runs.

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 dense sentences with no filler. It front-loads the core purpose, then adds the critical null-value nuance. 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?

Given the single parameter and no output schema, the description does well to specify record granularity, metric fields (tokens by kind, machine time, agent/model/host), totals, and null/reporting semantics. It could be more explicit about the exact response shape, but nothing essential for calling 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?

Schema description coverage is 100%: the only parameter 'key' is described as an issue key with an example ('UK-1'). The description adds no additional meaning for this parameter, and at high schema coverage 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 description clearly states the tool's purpose: retrieving background-agent run costs for an issue, with one record per run plus totals. The verb and resource are specific, and the distinction from the write-oriented siblings (report_agent_usage, delete_agent_usage) is inferable, though not explicitly stated.

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

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

No guidance is given on when to use this tool versus alternatives, and no exclusions or prerequisites are mentioned. The sibling tools imply a contrast, but the description itself does not help an agent decide between them.

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

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

No annotations exist, so the description carries the full burden. It discloses base64 encoding, text-based travel, size cost (roughly a third more), a size ceiling, and permission requirements. It doesn't mention error handling or explicit read-only status, but 'Read' implies non-mutating. This is strong transparency given the absence of annotations.

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 moderately long but every sentence adds value: purpose, encoding, cost warning, alternative, and permission. The core purpose is front-loaded, and the caveats follow naturally. No redundant 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 read tool with no output schema, the description covers what the output looks like (base64), the cost implication, the alternative approach, and access requirements. It doesn't specify error behavior (e.g., missing file) but that's minor. Overall, an agent has enough to invoke it correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by clarifying that 'filename' must match exactly what get_issue lists, and that 'key' is the issue key. It reinforces the parameter usage beyond the schema's basic definitions.

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 'Read' and the resource 'one file attached to an issue', specifies base64 encoding, and distinguishes it from wiki attachments and the pm-files server. An agent can immediately understand what this tool does and how it differs from 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?

Explicitly explains when to use this tool (reading an attachment as text), and when not to (when size is a concern, use the pm-files server instead), and points to local_files_setup for connecting. It also clarifies the only prerequisite: permission to see the issue.

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 must carry the full behavioral disclosure. It discloses that large diffs arrive cut, which is valuable. However, it does not explicitly state that the operation is read-only or mention authentication, rate limits, or error behavior. While the read-only nature is implied, the lack of explicit safety declaration is a gap.

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 concise two-sentence statement with no fluff. It front-loads the core purpose ('The files one merge request, pull request or commit touches, with their diffs') and then adds a necessary caveat ('Large diffs arrive cut'). Every sentence 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 simple read tool with two well-documented parameters and no output schema, the description covers the main functionality and a key limitation. It does not specify the exact return format (e.g., list of file paths with diffs), but this is largely implied. An explicit read-only note would improve completeness, but it is fairly complete as-is.

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 input schema covers both parameters with detailed descriptions, achieving 100% coverage. The description does not add significant parameter-specific information beyond the schema; it mentions the change parameter accepts MR/PR numbers or commit hashes, which is already in the schema. 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 description clearly states the tool retrieves files touched by a merge request, pull request, or commit, along with their diffs. This distinguishes it from siblings like read_code or search_code, which operate on individual files or search content. It is specific about the resource and action, though it does not use an explicit verb like 'get'.

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 when you need to see which files a change affects and their diffs. It does not explicitly mention when to avoid using it or compare to alternative tools such as read_code or search_code. The scope is clear, but no exclusions or alternative routing are provided.

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 burden and does well: it discloses the required permission ('permission to see the issue'), the stable id for follow-up mutation, and the auth requirement for the picture content ('with this same token'). It doesn't cover pagination or failure modes, but for a read it is substantive.

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?

Dense but front-loaded: the core action and resource come first, then the field inventory. The long run-on enumeration sacrifices some readability 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 single-param read with no output schema, the description fully defines the return object (id, checked, text, depth, reminder, picture, content), the permission requirement, and the follow-up tool. Nothing an agent needs to call or consume 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?

Schema coverage is 100%, and the sole parameter 'key' is fully documented in the schema ('Issue key, e.g. UK-1.'). The description adds no param-level meaning, 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 ('Read') and resource ('an issue's checklist — the '- [ ]' lines of its description') and distinguishes itself clearly from the sibling check_checklist_item, which it explicitly routes to. An agent can tell exactly what this 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 implies when to use it: to read checklist items and get the 'id' needed for check_checklist_item. The reference to check_checklist_item provides a clear handoff, but there is no explicit when-not or alternative for reading checklist content.

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 fully carries the behavioral burden. It discloses the default pagination direction, the meaning of the 'earlier' field (which would be in the response), the exact preservation of 'body' text (critical for matching edits), the 'replyTo' field semantics and how to use it with add_comment, that deleted comments are omitted, and the permission requirement. This is comprehensive and adds significant value 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?

The description is dense and packed with useful information, front-loaded with the core purpose. It is somewhat long, but every sentence contributes to usage, pagination, or response semantics. While it could be slightly tightened, the length is justified given the complexity of pagination and the lack of an output schema. It is well-structured and not verbose.

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 that there is no output schema, the description compensates by explaining response fields (body, replyTo, earlier) and the pagination mechanism. It covers permission requirements and the default behavior. It provides all necessary information for an agent to call the tool correctly and interpret the response, making it complete for a read operation.

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 provides descriptions for all three parameters (100% coverage), but the tool description adds valuable semantic context beyond the schema. It clarifies that startAt is counted from the oldest comment, explains the default behavior when startAt is omitted, and provides a concrete pagination recipe ('pass startAt - limit from a previous answer'). This goes beyond the schema's basic field descriptions.

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 reads comments on an issue, with a specific verb ('Read') and resource ('discussion on an issue'). It distinguishes itself from comment-writing siblings like add_comment and update_comment by focusing on reading. The opening sentence is unambiguous and leaves no doubt about the tool's 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 provides explicit guidance on when to use the tool (to read discussions) and explains the default pagination behavior (most recent comments) and how to walk back with startAt. It also notes that it is needed to fetch the text for update_comment edits, and states the only permission required. It does not explicitly name alternatives, but the context of siblings makes it clear this is the read tool for 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 behavioral burden. It discloses that 'comments' is a count rather than text, that visibility to the token is a precondition, and that important context may live in the comment thread rather than the description. It does not describe error behavior or response shape, but it covers the most misleading gotcha.

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 dense but every sentence earns its place: purpose, field scope, visibility condition, and a critical caveat about comments. It is structured so that the core retrieval purpose comes first, with the behavioral warning immediately after.

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, the description covers what is returned, the visibility condition, and the critical comments-count caveat. It does not specify error handling or exact response structure, but an agent has enough to invoke and interpret the result correctly in most cases.

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 describes the only parameter 'key' at 100% coverage with an example. The description reinforces that the key identifies the issue and determines visibility, but adds no substantial parameter syntax or format information beyond the schema.

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

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

States a specific verb and resource: 'Get one issue by key'. It lists the exact fields returned (description, status, assignee, labels, sub-tasks, links, wiki pages) and the visibility condition, which clearly differentiates it from broader tools like search_issues or get_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?

Provides explicit guidance to use get_comments whenever the comments count is non-zero, explaining why the thread often contains key information. It also implies a without-visibility condition ('if visible to this token'), but does not explicitly cover when to prefer search_issues over this tool.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses read-only journal semantics, newest-first ordering, the full set of outcome values with meanings ('applied', 'alreadyThere', 'tooLong', duty outcomes), and access control ('Any member may read it').

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 text is dense but every clause earns its place: the outcome enumerations are essential given the absence of an output schema, and the final guidance/access sentences add distinct value. The core purpose is front-loaded.

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

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

For a tool with no output schema and no annotations, the description fully compensates: it defines the entry content, all possible outcomes and their consequences, ordering, and who may read it. An agent can predict the returned data without further lookup.

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 projectKey, id, and limit. The description adds no parameter-specific meaning beyond the schema, so 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 project rule's journal, newest first,' immediately identifying the specific resource and operation. It details what each entry records (which issue, who moved it, outcome) and enumerates the outcome vocabulary, making the tool's function unmistakable and distinct from siblings like list_project_rules and update_project_rule.

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 an explicit diagnostic use case: 'The place to look when a checklist did not appear or an agent did not take an issue.' It does not name sibling alternatives or state when not to use it, but the context is clear enough for selection.

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 thoroughly. It discloses ordering ('Steps not yet done come first'), access-control behavior ('Only steps the caller may take are listed'; hidden steps are counted with a note), the instruction never to ask for secrets in chat, and the default project behavior. This is far beyond a generic read-only hint.

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 long but every sentence carries a distinct behavioral detail, and the primary purpose is front-loaded. It could be clearer with bullet-like structure, but there is no wasteful 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?

Since no output schema is provided, the description correctly compensates by defining the key return fields ('id', 'scope', 'done', 'why', 'how'), the hidden count with note, and the projects list. Given the one optional parameter and no annotations, this is complete enough for correct invocation.

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

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

The schema only says 'project' is an optional key with an example, but the description explains the actual behavior when omitted: the caller's only visible project is used, or if multiple exist, 'projects' is returned and only company steps are answered. This adds meaningful semantics beyond the input 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?

The description clearly names the resource and action: it reports what setup steps remain and what is already set up for a company and one project. It also gives an explicit invocation cue, 'when the person has just started or asks what else the tracker can do', and is distinct from the many get_* sibling 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?

It provides clear context for when to call the tool and explains project-selection behavior when no project is supplied or when multiple projects exist. It does not explicitly state when not to use it or name an alternative, but no sibling appears to offer the same onboarding-checklist capability.

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 full behavioral burden and handles it well: it discloses what data is included, that HTML is converted to text, and the access-control rule distinguishing letters tied to issues from other letters. This is especially valuable for an operation that reveals potentially sensitive content.

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 front-load the core behavior, then add only high-value context about ID sourcing and permissions. No filler or repetition of schema details.

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 operation with no output schema, the description covers return contents, how to get the ID, and who can read which letters. Nothing essential for 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?

Although the schema already documents letterId as 'The letter's id,' the description adds meaning by explaining where to obtain the id—from list_support_letters or get_support_request's messages. This provenance is the key semantic gap and is filled beyond the schema's tautological description.

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?

Description uses a specific verb and resource: 'Read one letter to the support address whole.' It goes beyond a mere restatement by enumerating what the tool returns—quoted thread, signature, HTML part as text, and headers—and differentiates from get_support_request's comment content and list_support_letters.

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 clear context for use by stating that letterId comes from list_support_letters or from get_support_request's messages, and implies when the full letter is needed versus the abbreviated comment. It does not explicitly state when not to use this tool, but the context is sufficient for a read-only single-resource operation.

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 fully carries the behavioral disclosure burden. It details what is returned, including the internal-comment visibility rule, autoRule/autoWording semantics, and the found=false behavior for non-support issues. This is thorough for a read operation, though it doesn't cover permissions or error formats.

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 dense sentence that packs in many relevant details without excessive verbosity. It front-loads the main purpose and each clause adds value, though it could be structured into clearer sections for easier parsing.

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 and no annotations, the description does an excellent job of describing the return payload structure and edge-case behavior. It lacks explicit error-handling details but is quite complete for a read-only 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% for the single 'key' parameter, which is well-documented with an example. The description adds no additional parameter-specific guidance, so a baseline score of 3 is appropriate since 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 opens with a clear verb ('Read') and resource ('who is behind a support request'), then enumerates the specific data returned (requester info, auth state, context, visible comments). This clearly distinguishes it from generic get_issue or get_comments, even without naming 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?

It implicitly defines its scope by stating it reads support requests and returns found=false for non-support issues, which guides when to use it. However, it does not explicitly compare with alternatives like get_issue or list_support_queue, so some inference is required.

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 full behavioral disclosure. It reveals the output is base64-encoded bytes, warns about size/cost overhead ('cost roughly a third more than the file itself'), mentions a size ceiling, and offers a fallback. It also clarifies the two identification modes. This is far beyond a bare read description and leaves nothing hidden about side effects or prerequisites.

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 three sentences, front-loaded with the core purpose, then gives the copy workflow, then the size/alternative note. Every sentence earns its place; there is no filler. The structure moves from 'what' to 'when' to 'caveats' efficiently.

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's moderate complexity (two identification schemes, output format, size limits, alternative server), the description covers everything an agent needs: how to identify the page and file, what the response contains, why it might not be suitable, and what to do instead. No output schema exists, so the description appropriately explains the base64 return. The only omission is error behavior for missing files, which is minor for a read operation.

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 each parameter. The description adds meaning by explaining the relationship between pageId and spaceKey+title (two alternative identification methods) and clarifying that filename should match what get_wiki_page lists. It also ties pageId to search_wiki via the schema, and the description's context about copying gives the parameters purpose. This exceeds the baseline 3 for full schema 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 opens with a specific verb and resource ('Read one file attached to a wiki page'), states the output format (base64-encoded bytes), and identifies the page by two explicit methods (pageId or spaceKey+title) and the file by filename as listed by get_wiki_page. It clearly distinguishes itself from siblings like add_wiki_attachment and delete_wiki_attachment by framing the read as the copy source.

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 explicit when-to-use guidance: 'This is how a file is copied from one page to another: read it here, write it with add_wiki_attachment.' It also provides an explicit alternative for larger files or disk storage, pointing to the pm-files MCP server and local_files_setup, and states the permission requirement ('Reading needs only permission to see the page'). No inference is left to the agent.

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 meets it: token-visibility filtering, default plain-text vs Markdown mode, comment metadata needed for update_wiki_comment, and the partial-read semantics for large pages. It also notes the performance tradeoff ('reading costs less as text') without contradicting any annotation.

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 dense, purposeful sentences with the core purpose and lookup modes front-loaded. Every sentence earns its place, and the parenthetical clarifications resolve schema-level ambiguities such as how anchors are named and what the default limit is.

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

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

For a 9-parameter read tool with no output schema and no annotations, the description covers the full decision path: what it fetches, when to choose Markdown, how to navigate large pages, and how partial reads interact with update_wiki_page. No essential calling behavior is left undocumented.

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 input schema already documents all 9 parameters at 100% coverage, so the baseline is 3. The description adds relational workflow meaning: start with outline, then section or offset/limit, and enable withMarkdown only when edits are intended. This goes beyond restating the schema without duplicating it.

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

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

The description opens with a specific verb and resource: 'Get one wiki page by id, or by space key + title', and then enumerates what is returned: text, labels, parent/child pages, comments, and linked issues. It also distinguishes itself from update_wiki_page by describing the edit handoff workflow, so an agent can tell the read operation apart from its 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?

It gives clear context: use this for reading a page, pass withMarkdown when preparing to edit, and use outline/section/offset/limit for partial reads of large pages. It does not explicitly state when to prefer sibling tools like search_wiki or get_comments, so it stops just short of full when-to-use/when-not-to-use guidance.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It thoroughly covers: the direction encoded in the phrase, refusal of unsupported phrases with a listing, idempotency, permission requirements, and the effect on get_issue returning 'links'. This exceeds what the schema alone conveys.

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 detailed but each sentence adds value. It is front-loaded with a concrete example and logically organized: example, semantics, refusal, idempotency, permissions, and effect on get_issue. While longer than minimal, it is appropriately sized for the complexity of the tool and avoids 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 tool with 3 required parameters and no output schema, the description is remarkably complete. It covers usage semantics, edge cases (unknown phrases), side effects (link appears on both issues), idempotency, permission requirements, and how to observe the result (get_issue returns 'links'). An agent has all necessary information to invoke it correctly.

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

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

Schema coverage is 100%, giving a baseline of 3, but the description adds significant semantic depth. It explains that 'type' is the phrase as spoken, clarifies the directionality via 'from' and 'to', and notes that arguments cannot disagree. It also gives examples and explains the refusal behavior, going well beyond the schema's field descriptions.

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 'Link two issues' with a concrete example using specific issue keys and a phrase. It differentiates from siblings like unlink_issues by describing the linking operation precisely, and the scope (two issues) is 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?

The description provides clear context on when to use the tool, including the idempotency behavior ('linking the same pair the same way again changes nothing') and the permission requirement to edit both issues. However, it does not explicitly name alternatives or contrast with tools like unlink_issues, so it stops short of full exclusion 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?

Since no annotations are provided, the description carries the full behavioral burden. It discloses key behaviors: the link persists and is visible on both sides, it survives page renames/moves, and re-linking the same page updates the existing link rather than creating a duplicate. It also notes the edit-permission requirement. While it doesn't cover error cases or rate limits, it provides substantial behavioral transparency.

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

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

The description is compact and front-loaded with the primary purpose. Each sentence adds essential information: the action, the persistence behavior, identification methods, idempotency, and permission requirement. No filler or redundancy exists, making it efficient for an agent to parse.

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

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

For a tool with five parameters and no output schema, the description covers the key operational aspects: how to identify the target page, the effect of linking, idempotency, and required permissions. It doesn't detail error handling or return values, but those are less critical for a link operation. Overall, it provides enough context for correct invocation.

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

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

The schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds meaningful value by explaining the two mutually exclusive identification methods (pageId vs. spaceKey+title) and that linking again updates the existing link, which clarifies how the parameters are intended to be used together. This goes beyond the schema's individual parameter descriptions.

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: 'Link a wiki page to an issue.' It specifies the resource and the relationship, and differentiates from sibling tools like link_issues by focusing on wiki pages. The detail that the link appears on both entities and survives renames/moves further clarifies the operation, making it 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?

The description gives clear instructions on how to identify the page (by pageId or spaceKey+title) and mentions a permission requirement, but it does not explicitly state when to use this tool over alternatives like link_issues or unlink_wiki_page. No when-not-to-use guidance is provided, so the usage context is only 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 behavioral burden. It discloses an important permission limitation ('Only repositories whose owners opened them to agents can be read') and implies a read-only operation. However, it omits output format, whether listings are recursive, and behavior on inaccessible or invalid paths.

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 one front-loaded sentence with no filler. The main action is stated first, and the important ownership caveat is included without 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 read-only listing tool with three optional parameters, the description is workable, but there is no output schema and no mention of what a successful call returns. It also lacks sibling routing guidance, leaving an agent to infer the output and alternative tools.

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%, with all three parameters documented including defaults and usage notes, so the baseline is 3. The description adds only the 'connected to a project' scope and ownership constraint, not additional parameter-level meaning.

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 action ('List a directory') and a clear resource ('a repository connected to a project'). It does not explicitly differentiate itself from siblings like read_code or search_code, so it misses the top score.

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

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

No guidance is given about when to choose this tool over read_code or search_code, nor are exclusions or alternatives mentioned. The ownership caveat is a useful precondition, but it does not help an agent decide between sibling tools.

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

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

There are no annotations, so the description must carry the behavioral burden. It does so by disclosing a permission scoping ('this token may read'), the return boundary ('names and who attached them'), and a security-sensitive guarantee ('never the values'). It could go further by describing what happens when neither parameter is supplied, but the disclosed behavior is clear and non-obvious.

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 with no filler. The core purpose is front-loaded, the return limitation follows immediately, and the operational note is placed last. Every sentence 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 simple list tool with no output schema, the description states what is returned, what is deliberately not returned, which parameters to use, and when to switch to the related reveal_credential tool. Nothing essential for correct invocation or interpretation 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?

The schema has descriptions for both parameters, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the two parameters are used one-or-the-other ('Pass issueKey or pageId') and by mapping the credential source to issues or wiki pages. It does not fully resolve ambiguity about what happens if both are passed, but it materially improves schema-only guidance.

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

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

The description opens with a specific verb and resource: 'List the credentials attached to an issue or a wiki page.' It also narrows scope to what 'this token may read' and explicitly states the return content ('names and who attached them, never the values'), which clearly distinguishes it from sibling reveal_credential.

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 tells the agent to pass 'issueKey or pageId' and explicitly routes value-reading to reveal_credential, adding the condition 'only when you are about to use it.' This gives an explicit alternative and a behavioral guardrail, which is strong usage guidance.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses the ten-deployment cap, the ordering of environments, the permission model ('any member may read'), and the semantic side effects (issues report deployedTo, get one history line per environment, and trigger 'deployed' project rules). It omits pagination and detailed return formatting, which keeps it from a 5.

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

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

It is one front-loaded paragraph that leads with the resource, which is good. However, several sentences (history lines per environment, 'deployed' rule triggers, deployedTo cross-reference) explain downstream semantics that are tangential to selecting and invoking the tool, adding length without sharpening the call decision.

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 describe the return surface, and it does so reasonably well: environments in order, ten newest deployments, canEdit and canReport flags. It is complete enough for an agent to understand what it gets, though exact response shape and any pagination remain unspecified.

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 parameter (projectKey) with 100% schema description coverage, so the schema already documents it fully. The description adds no format or syntax detail beyond what the schema provides, which is the baseline-3 case 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 states the specific resource and scope: a project's environments in order plus its ten newest deployments. It clearly defines the domain concepts (environment, deployment, deployedTo, canEdit/canReport), so the agent understands what comes back. It does not, however, name or distinguish the tool from siblings like set_environments or report_deployment, which would push it to a 5.

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

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

There is no explicit guidance on when to call this versus alternatives. 'Any member may read them' is a permission note rather than a usage condition, and set_environments (the write counterpart) is never mentioned. The agent must infer usage entirely from the resource description.

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

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

No annotations exist, so the description carries the full burden of behavioral disclosure. It reveals key behavioral facts: the role default shifts based on presence of a key, only open questions return by default, and state='all' adds answered, withdrawn, and expired ones. It also warns that ask_issue_question does not wait, so this tool is the polling mechanism; only the exact return shape is left implicit.

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 dense sentences, each earning its place: purpose and scopes in the first, polling use-case and caveat in the second, parameter defaults in the third, and state filtering in the fourth. Nothing is wasted or redundant.

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 moderately complex list tool with no output schema, the description covers purpose, defaults, role semantics, state behavior, and the polling relationship with ask_issue_question. It leaves 'from' and 'limit' semantics to the schema, and the exact return shape is only implied by 'questions with answer options' rather than stated, which is a modest 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 the baseline is 3. The description reinforces the key/role default interaction and state='all' behavior, but it does not add semantically new information beyond what the schema already provides for each parameter.

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

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

The description states a precise verb and resource — listing issue questions with their answer options — and distinguishes the three meaningful scopes via role values ('to_me', 'asked', and everything on one issue). It clearly separates this read/poll operation from sibling tools like ask_issue_question and answer_issue_question.

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 explicitly frames this as the way to poll: 'This is how you find out whether the question you asked has been answered — poll it, since ask_issue_question does not wait.' It also explains how defaults change with and without a key, giving the agent clear context for when to call it. It does not explicitly contrast it with answer_issue_question or withdraw_issue_question, but the read-versus-write distinction is clear from context.

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

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

With no annotations, the description carries the full behavioral burden. It helpfully discloses the returned fields and hints at a permission/role gate, but omits pagination behavior beyond the limit param, ordering, and what happens when no acts are readable.

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 core action and the resource. The parenthetical field list is informative rather than wasteful, though 'what this installation's agents have already read off the official sites' is slightly verbose.

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

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

With no output schema, the description usefully spells out the returned fields, which an agent cannot get elsewhere. It is reasonably complete for a simple list tool, lacking only ordering/pagination behavior and clearer access 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 limit and filter are already fully documented in the schema. The description adds no syntax, format, or semantic detail beyond what structured fields provide, 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+resource ('List the acts in the legal library') and even enumerates the fields returned (url, title, fetched_at, checked_at, length). It does not, however, explicitly distinguish itself from the sibling search_legal_library, so an agent must infer the difference from the verb 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?

The trailing phrase 'Open where the company lets an agent role read laws' gestures at an access condition but is too cryptic to act on. There is no explicit when-to-use guidance and no mention of the obvious alternative search_legal_library for filtered lookups.

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?

There are no annotations, so the description carries the behavioral disclosure burden. It meaningfully discloses that auth tokens are never returned, only whether one is set, which is important context for an agent invoking the tool. It does not mention pagination or output shape, but for a simple list operation this is acceptable.

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 filler. The first sentence states the core action and scope, and the second adds a critical safety-relevant caveat about auth tokens.

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

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

The tool is low-complexity: one required parameter, no nested objects, and no output schema. The description covers purpose plus the most important behavioral caveat about secrets. It does not enumerate the full response fields, but that is not a critical omission given the simple nature of the 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?

The only parameter, projectKey, is already fully described in the schema with an example ('UK'). The description adds no additional parameter semantics, so the baseline score of 3 for high schema coverage 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 and resource: 'List the external MCP connections configured for a project.' It clearly distinguishes this from sibling tools like upsert_mcp_connection and list_credentials, so an agent knows exactly what resource is being read.

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

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

The phrase 'configured for a project' implies the tool is for retrieving existing MCP connections for a given projectKey. However, it does not explicitly state when to prefer this over related tools like list_credentials or upsert_mcp_connection, nor does it give exclusions for 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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It explicitly states that the operation is read-only and accessible to any member, which is important safety context. It also describes the returned content in useful detail, including the customfield_ suffix for JQL search, but stops short of defining pagination, ordering, or error behavior.

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 compact and front-loaded, explaining the core subject in the first clause, then adding precise details about field kinds, colours, and JQL relevance. Every sentence contributes meaningful information and 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?

For a read-only, one-parameter tool with no output schema or annotations, this description covers the key aspects: what the tool returns, the JQL connection, and the access model. It does not explicitly describe the list/array return shape, but that is reasonably inferable from the tool name and phrasing. Missing guidance on alternatives is the main 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?

The schema has 100% description coverage for the single parameter projectKey, so the baseline of 3 applies. The description adds project context and mentions customfield naming, but it does not elaborate on the value format or relationship of projectKey to the returned fields beyond 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 states that the tool surfaces the columns a project keeps about its issuesholistically covering name, kind, list options, and customfield names. The final sentence, 'Any member may read them,' makes the read operation explicit and distinguishes it from sibling mutation tools like set_project_field and delete_project_field. It lacks a crisp imperative verb like 'List', but the intent is 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?

There is no guidance on when to prefer this tool over alternatives such as set_project_field or delete_project_field. The permission note 'Any member may read them' implies general convenience, but no explicit when-to-use or when-not-to-use conditions are provided. Agents must infer usage context from the tool name and 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?

No annotations are provided, so the description carries the full burden. It does disclose a great deal of domain behavior (triggers, 'alreadyThere', 'tooLong', 'moveRefused', 'tooDeep', agent duties), which is genuinely valuable context. However, it is framed as spec documentation for building rules rather than as behavior of this read operation, and it never states whether the call is read-only, requires permissions beyond membership, or paginates. The closing 'Any member may read them' is the one piece of operation-level access transparency.

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

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

The description is an extremely long run-on block that buries the actual operation ('list') and its single parameter far from the start. Most of the text is rule-semantics documentation that belongs in create/update_project_rule, not in a list tool. It is neither front-loaded nor appropriately sized for a one-parameter read.

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-param read with no output schema, the description does end by enumerating the return shape (id, action, trigger, state, conditions, template, moveToStatus, on-state, agent, canEdit) plus the enumerations available, which is genuinely complete on the return side. But because there is no output schema and no annotations, the absence of explicit read-only/permission framing and the buried purpose leave real gaps.

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

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

Only one parameter exists (projectKey) and schema coverage is 100%, so the baseline is high. The description adds no per-parameter detail, but with a single fully documented required key there is little to add, warranting the 0-params/high-coverage baseline of 4.

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 an explanation of what a project rule does ('when an issue enters a state, a checklist from a template is appended to its description'), which is helpful background, but it never states plainly that this tool lists/reads project rules. The agent must infer the verb from the tool name. It distinguishes itself from create/update/delete_project_rule only implicitly via the closing 'Answers with each rule's id'.

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

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

There is no explicit statement of when to reach for this tool versus siblings like get_project_rule_runs, create_project_rule, or update_project_rule. The mention that 'the other rule tools take' the returned id implies this is the discovery step, but that is an inference rather than 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?

With no annotations, the description carries the behavioral burden. It reveals token-based visibility and the subproject model (own issues/board/wiki, shared access only). It stops short of describing pagination or return shape, but for a no-parameter list operation this is sufficient.

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 concise sentences, with the core operation in the first and a genuinely useful data-model clarification in the second. No filler or repetition of schema 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 parameterless read-only tool, the description is nearly complete: it covers access scoping and subproject semantics. It could mention ordering or return fields, but the absence is minor given the tool's simplicity and the lack of input 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?

No parameters exist, so the 0-parameter baseline of 4 applies. The description indirectly explains why no input is needed: results are determined entirely by the token's visibility.

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

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

States a clear action and resource: 'List the projects visible to this token.' It also clarifies token-scope behavior, so an agent can distinguish this read-only listing from project-creation or field-listing 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?

Provides clear context on when results are limited (project-scoped token) and explains subproject parent semantics. It does not explicitly name an alternative tool, but the read-only listing has no obvious sibling, so no exclusion is needed.

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. It discloses the return fields (id, reason, sender, subject, file names), the access restriction (full member of the support project), and the meaning of each state. It does not cover pagination or sorting, but for a list tool 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 dense but well-structured: it front-loads the purpose, then explains states, then lists return fields, and ends with access control. Every sentence contributes meaning; no redundancy or fluff, though it is longer than strictly 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 simple list operation with one optional parameter and no output schema, the description covers the essential aspects: states, default, return fields, and access. It omits minor details like sorting or pagination, but these are not critical for an agent to call the tool 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% for the 'state' parameter, so the baseline is 3. The description adds substantial value by explaining each state's meaning and the default behavior (held and failed), which goes beyond the schema's brief one-line description and helps the agent use the parameter correctly.

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 the specific verb 'List' and identifies the resource as 'letters to the support address' with a clear scope: letters that 'did not become part of a request.' It enumerates four states and clarifies the default behavior, distinguishing it from siblings like get_support_letter (singular) and list_support_queue (likely requests).

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 explains when to omit 'state' (to get held and failed) and defines each state, giving the agent context to decide if this tool fits. However, it does not explicitly name alternative tools or state when NOT to use it, relying on purpose clarity rather than explicit routing.

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

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

The description discloses significant behavioral details: the sorting order, the meaning of 'clock.turn', the definition of 'numbers' metrics, the exclusion of automatic acknowledgements/answers, and the 'autoRule' flag. It also notes readability permissions. With no annotations provided, the description carries the full burden and does so thoroughly.

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 dense but well-structured, front-loading the core purpose and sorting, then explaining the fields and metrics. It is longer than necessary but every sentence adds meaningful detail. It could be slightly more concise, but the structure is logical and scannable.

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's complexity (rich output with nested objects like 'numbers' and 'clock.turn'), the description is remarkably complete. It explains the sorting, the meaning of each status, the metrics, the exclusion of automatic answers, and the permission model. There is no output schema, so the description must explain return values, and it does so thoroughly.

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 describes the 'who' parameter with its allowed values and default. The description adds context by explaining the queue context and the meaning of the returned fields, but doesn't add much beyond the schema for the parameter itself. Since schema coverage is 100%, the baseline is 3, and the description's context around the parameter (e.g., 'mine' means assigned to you) is already in the schema, so a 4 is justified for the added context about the queue's purpose.

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 the support desk's queue with open requests, sorted by urgency, and details the fields returned. It distinguishes itself from sibling tools like get_support_request and list_support_letters by focusing on the queue with specific statuses and metrics.

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 when to use this tool: to view the support queue and its metrics. It doesn't explicitly state when not to use it or name alternatives, but the detailed scope and the 'who' parameter provide clear context for usage. Sibling tools like get_support_request are obviously for individual requests, so the usage context is clear.

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 must disclose behavioral details itself. It states that 'any member may read them,' indicating read-only access, and explains the track model. However, it does not describe the output format, pagination, or error handling, which is a notable gap for a listing tool. The response structure is left unspecified.

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 well-structured and clearly explains the track concept, front-loading the core purpose. It is somewhat verbose for a simple listing tool, but the extra explanation serves to differentiate tracks from subprojects. The sentences flow logically and no information 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?

The description covers the conceptual model and access rules, but omits the response structure and any edge cases such as what happens when a project has no tracks or when the project key is invalid. Since there is no output schema, the agent is left to infer what the tool returns. For a one-parameter tool, this is a significant 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?

The schema already describes the projectKey parameter with an example ('TH'), and the description adds no additional parameter-specific details. Since schema description coverage is 100%, the baseline of 3 applies; the description does not enhance understanding of the parameter 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 conveys that the tool returns the tracks associated with a project, and clarifies the track concept as labels. It distinguishes tracks from subprojects, which helps differentiate from related tools. However, it does not use an explicit verb like 'list' and instead describes the concept, making the action slightly indirect.

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 mentions that tracks differ from subprojects and references create_project's parentKey for subproject creation, giving some context. However, it does not explicitly state when to use this tool versus alternatives like set_track or remove_track, nor does it provide explicit when-not-to-use guidance. Usage is implied but not fully articulated.

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 burden. It discloses token-visible project scoping, filtering by username/display name/email, and the critical behavior that mentions match username but not display name. Ordering and return shape are not mentioned, but this is adequate for a non-destructive list 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?

Three sentences with no fluff: scope, filters, and usage semantics. Key constraints are front-loaded and every sentence 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?

Given 4 optional params, no output schema, and no annotations, the description covers the core use case, filtering, and the subtle username/display-name distinction. It doesn't explicitly list return fields, but the fields named in text and schema provide sufficient guidance.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful cross-tool semantics beyond the schema: the [~username] mention syntax, the username-not-display-name matching rule, and how to pass the same value as assignee.

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 action (list) and resource (users), defines the population as members of projects visible to the token, and clearly differentiates from sibling tools by tying to assignment/mention use case.

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 context for when to call: when you need users to assign work to or mention, with guidance on how to reuse the returned usernames in mentions and as assignee. Doesn't name exclusions, but no close alternative exists among siblings.

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 supplied, so the description carries the full burden, and it does disclose meaningful behavior: 'Any member may read them' establishes the permission profile, and it defines non-obvious result semantics such as archived ('put away: still on its issues, no longer offered') and 'overdue'. It stops short of describing pagination, result-size limits, or ordering guarantees, which keeps it below a 5.

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

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

The purpose is front-loaded in the first sentence, but the rest is a dense, em-dash-heavy data dictionary enumerating every returned field and its meaning. Much of that belongs in an output schema, and the run-on phrasing ('Also \'canEdit\': whether you may make, change and release versions here') hurts scannability.

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 explain return values and it does so thoroughly — id, name, description, dates, released/archived, overdue, issue and open counts, canEdit — plus a permission statement. For a two-parameter list tool this is largely complete, though ordering/pagination remains unstated.

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