Kaiku is an issue tracker with a wiki, built so that people and AI agents work in the same place. Its hosted MCP server lets an agent search, read, file and update issues, comment and answer questions, read and write wiki pages, and attach files — with the permissions of the person whose token it uses. Create a token in Settings → Connect over MCP and send it as Authorization: Bearer (or in X-Api-Key); the token says which workspace.
Scored across 73 tools
Each tool targets a distinct resource-action pair—issues, wiki pages, support letters, admin reports, code—and the detailed descriptions disambiguate close pairs like add_comment vs add_wiki_comment. A few near-twins remain (admin_bank_transfer vs admin_set_bank_transfer, get_support_letter vs get_support_request, list_project_rules vs get_project_rule_runs), but their descriptions make the boundaries clear enough.
The set mostly follows a consistent verb_noun pattern (add_, create_, get_, list_, update_, delete_, admin_), making it predictable. Irregularities like admin_set_bank_transfer instead of admin_update_bank_transfer, set_issue_fields vs set_project_field, and list_project_rules vs get_project_rule_runs keep it from being fully consistent.
73 tools is far beyond the well-scoped range and crosses the extreme threshold even though the server covers many domains. An agent must navigate an unwieldy surface, and the sheer size hurts selection reliability more than the individual clarity helps.
Coverage is notably strong for the broad domain: issue lifecycle (minus deletion), wiki CRUD, support queue and letters, admin reports, code reading/search, and credential handling are all present. Gaps are minor but real—no delete_issue or delete_comment, and admin tools are almost entirely read-only—so some workflows cannot be fully closed.
Attach a file to an issue: pass its bytes as 'contentBase64', or its content as 'text' when the file is text. Attaching a filename the issue already has replaces that file rather than adding a second copy, so retrying this call cannot double it. Returns the attachment's download URL. Requires permission to edit issues in that project.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| text | No | The file's content as text, stored as UTF-8 — for a log, CSV or Markdown file you are writing here. Alternative to 'contentBase64'; passing both is refused. | |
| filename | Yes | File name to store, e.g. 'report.pdf'. Any directory part is dropped. | |
| mimeType | No | Content type to record for the listing, e.g. 'text/csv'. Ignored when the bytes identify themselves (a PNG is a PNG whatever you call it), and never used to serve the file. | |
| contentBase64 | No | The file's bytes, base64-encoded (a 'data:…;base64,…' URL is accepted and unwrapped). Use 'text' instead when the file is text. |
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 delivers: it discloses that reusing an existing filename replaces the old file, retrying is safe, a download URL is returned, and editing permission is required. This is substantial, non-obvious behavioral context beyond simply 'attaches a file'.
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 compact sentences, each earning its place: payload selection, replacement/idempotence semantics, return value, and authorization. The most important usage information 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 5 parameters, no annotations, and no output schema, the description plus schema gives an agent everything needed to call it correctly: parameter choice, duplicate-handling behavior, return value, and permission requirements. No critical operational gap remains.
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, but the description adds meaningful cross-parameter guidance: use 'text' for text files and 'contentBase64' for bytes. It also clarifies the 'filename' parameter by explaining replacement behavior. The remaining parameters are already well documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: attach a file to an issue. It also distinguishes the two ways to provide the file and naturally differentiates from siblings like add_wiki_attachment by scoping to issues.
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 describes when to use the tool and which parameter to choose for binary vs text content, and it notes the required edit permission. However, it does not explicitly name sibling alternatives like add_wiki_attachment or state when not to use them, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to an issue, or reply to one of its comments ('replyTo' is a comment id from get_comments). A reply notifies the author of the comment it answers, whether or not they watch the issue — no mention needed — and they are told once even if also mentioned. Requires permission to comment in that project (read-only members cannot). Answers with 'notified' (who this actually reaches, the answered author included), 'answered' (for a reply: whose comment it answers, and 'notified' false with a 'reason' when they are not told) and 'unresolvedMentions' (what looked like a mention and reached nobody, each with a reason) — a wrong handle is stored as written and never refused, so that list is the only sign it did not land. Where the workspace has agents, [~agent:role] (e.g. [~agent:product]) calls one to answer in the thread on your behalf: 'agents' lists each call with its requestId and status, and an agent that will not come is in 'unresolvedMentions' with its reason (agent_unknown, agent_off, agent_plan, agent_budget, too_many).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| body | Yes | Comment body. Markdown is kept as written, and carries $…$ / $$…$$ LaTeX formulas and [~username] mentions (the username, which list_users hands you ready-made — never the display name). | |
| replyTo | No | The comment this one answers, as returned by get_comments — on the same issue and not deleted. |
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.
Attach a file to a wiki page, identified by 'pageId' or by 'spaceKey' + 'title': pass its bytes as 'contentBase64', or its content as 'text' when the file is text. Re-attaching a filename the page already has replaces its bytes and bumps its version, as the wiki does everywhere else, so retrying this call cannot leave two copies. An attached file is not on the page until the body references it — the answer hands you the Markdown to add with update_wiki_page. An image may also carry a dark-theme version, attached as the same name with '-dark' before the extension (diagram.svg + diagram-dark.svg); the body still references the plain name. Requires permission to edit the page.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | The file's content as text, stored as UTF-8 — for a log, CSV or Markdown file you are writing here. Alternative to 'contentBase64'; passing both is refused. | |
| title | No | Exact page title, when identifying the page by title. | |
| pageId | No | Page id (as returned by search_wiki). | |
| comment | No | Short note about this upload, shown in the page's attachment list. | |
| filename | Yes | File name to store, e.g. 'diagram.png'. Any directory part is dropped. | |
| mimeType | No | Content type to record for the listing, e.g. 'text/csv'. Ignored when the bytes identify themselves, and never used to serve the file. | |
| spaceKey | No | Space key, when identifying the page by title. | |
| contentBase64 | No | The file's bytes, base64-encoded (a 'data:…;base64,…' URL is accepted and unwrapped). Use 'text' instead when the file is text. |
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 thoroughly. It discloses idempotent re-attachment behavior (replacing bytes and bumping version), the fact that attaching does not place the file on the page until referenced, the dark-theme variant naming, and the permission requirement ('Requires permission to edit the page'). This goes well beyond a minimal 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 dense but well-organized: it front-loads the core action and identification methods, then covers content modes, re-attachment behavior, the page-reference caveat, dark-theme naming, and permissions. Every sentence adds value, though the length is slightly high for a tool whose schema already documents parameters. Still, the extra sentences are all behaviorally relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers identification, content input, idempotency, the need to follow up with update_wiki_page, dark-theme variants, and permissions. An agent has everything needed to invoke it correctly and to understand the post-conditions.
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 adds meaningful semantics beyond the schema: it explains the relationship between 'text' and 'contentBase64' (mutually exclusive, both refused if passed), the dark-theme suffix convention for filenames, and the fact that directory parts are dropped. It does not enumerate every parameter, but the schema already covers them, and the description clarifies the non-obvious interactions.
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 ('Attach'), a resource ('a file to a wiki page'), and the two identification methods ('pageId' or 'spaceKey' + 'title'). It also distinguishes the content input modes ('contentBase64' vs 'text'). This clearly differentiates it from siblings like add_attachment (generic attachment) and get_wiki_attachment (retrieval).
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 explains when to use this tool: to attach a file to a wiki page, and it names the follow-up tool (update_wiki_page) for adding the Markdown reference to the page body. It also clarifies the alternative content input modes and the dark-theme naming convention, giving an agent enough context to select and invoke it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Comment on a wiki page, or reply to one of its comments ('replyTo' is a comment id from get_wiki_page). A reply notifies the author of the comment it answers, whether or not they watch the page — no mention needed — and they are told once even if also mentioned. Identify the page by 'pageId', or by 'spaceKey' + 'title'. Markdown is rendered; mention someone as @Their Name, the wiki's own form. Requires permission to comment in that project. Answers with 'notified' (who this actually reaches, the answered author included), 'answered' (for a reply: whose comment it answers, and 'notified' false with a 'reason' when they are not told) and 'unresolvedMentions' (what looked like a mention and reached nobody, each with a reason) — a wrong handle is stored as written and never refused, so that list is the only sign it did not land.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Comment body as Markdown, which also carries $…$ / $$…$$ LaTeX formulas. | |
| title | No | Exact page title, when identifying the page by title. | |
| pageId | No | Page id (as returned by search_wiki). | |
| replyTo | No | The comment this one answers, as returned by get_wiki_page. | |
| spaceKey | No | Space key, when identifying the page by title. |
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.
Administrators only: where a bank transfer is to be sent (PM-625) — beneficiary, account and its own currency, bank and SWIFT, the intermediary bank if there is one, the purpose line, how many days a wire is given, and who last changed all of it. 'offered' is the one flag that answers «may a customer pick a transfer right now»: it is switched on AND carrying everything a payment needs, which is not the same as 'enabled'. A bill already issued carries its own frozen copy of these details and is not changed by what this returns. Amounts are always USD, whatever the account's own currency is.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Administrators only: the error collector's week — events and distinct errors per project against the week before, errors first seen that week with their release, the loudest by events and by people, and errors that came back after being resolved. The same numbers the weekly error report carries. A project the collector did not answer about has null counts and a reason, never zeros. Ask for an earlier week with weeksAgo.
| Name | Required | Description | Default |
|---|---|---|---|
| weeksAgo | No | 0 is the last full week, 1 the one before it. |
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.
Administrators only: the installation as a business over a period — registrations, how many of them became working companies, purchases and conversion by cohort, churn, and money. Money comes in two halves that must not be added together: 'stock' is what recurs every month at today's prices, 'revenue' is what actually arrived inside the period. Each carries its own currency. Figures come from the fleet's ledger, so 'machines' says how current each machine's copy is — a machine that is behind makes the totals older than they look, it does not make them wrong. 'activation' is how many of the companies registered in the period have had their first agent come in (the first request with a configured token), and how soon — within the hour, the day, the week. 'ai' is AI as money over the same period — what our key's calls cost at each provider, what companies were charged, the margin, the cost nobody was charged for and why, what has accrued and what 'ai' invoices still want — and is neither in 'stock' nor in 'revenue'. Its totals are null, never zero, while a machine has not reported its AI: 'ai.missing' names it and 'ai.reported' is the sum over the machines that did. Default period: the last 90 days.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the period, as YYYY-MM-DD, included. Use with 'from'. | |
| days | No | How many days back from today. Defaults to 90, at most 730. Ignored when 'from' and 'to' are given. | |
| from | No | Start of the period, as YYYY-MM-DD. Use with 'to'. |
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.
Administrators only: what companies were asked to pay and what answered it — each invoice with its amount, its coin, whether it is paid and what is short, and the payments against it. Amounts are never added across coins: each row carries its own currency and they stay apart. The list is the fleet's ledger, so 'machines' says how current each machine's copy is. One invoice's delivery record belongs to the machine that took the payment and is not rolled up — the answer says so where it is missing rather than showing an empty list.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Only invoices of the company at this address. | |
| limit | No | How many rows, newest first. Default 50, at most 100. | |
| status | No | Only invoices in this state, e.g. 'open', 'paid', 'void'. |
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.
Administrators only: the landing site's week — visits, where they came from, clicks on sign-up, and the registrations that followed. The same numbers the weekly report carries into the monitoring chat. Ask for an earlier week with weeksAgo. The rendered message is not returned, only the figures.
| Name | Required | Description | Default |
|---|---|---|---|
| weeksAgo | No | 0 is the last full week, 1 the one before it. |
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.
Administrators only: how loaded this machine is and what the language models cost. Load is this machine's own — database, streams, memory, processor, traffic and stored bytes, each as used against allowed, where an allowance is known. Model spend covers the assistant, search-by-sentence and translation over a rolling window, with totals and breakdowns by feature, by model and by day; costs are estimates from the prices recorded at the time. Who spent it is not returned here.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window for model spend, in days. Default 30; 0 means all time. |
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.
Administrators only: the whole installation by the numbers — accounts, workspaces, projects, issues, comments and sprints, plus issues broken down by status and by project. Counted across every workspace, which is what makes it the installation's rather than one company's. A total is null, never zero, when a machine of the fleet did not answer: 'fleet' says which machines were asked and which are missing, and 'here' is always what this machine counted. The breakdowns are this machine's. Read a null as 'nobody knows', never as 'none'.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
Administrators only, and this one CHANGES things: state where bank transfers are to be sent. Send the WHOLE set every time — anything left out is cleared, not kept, because details half of one bank and half of another are money sent to a mixture of two. Read admin_bank_transfer first and repeat what you are not changing. Switching the method on is refused while anything a payment needs is missing (beneficiary, account, swift, and a purpose line carrying {invoice}), and the refusal names the field; switching it off is never refused. 'minimumUsd' is a floor under the METHOD and not under the debt: a bill below it is offered the other ways to pay, and what is owed does not change. The change is recorded against the calling administrator. Bills already issued keep the details they were issued with.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | A line for the payer, e.g. which charges are whose. Shown with the details. | |
| swift | No | The bank's SWIFT/BIC. | |
| account | No | The account number or IBAN. | |
| enabled | Yes | Whether this installation takes transfers. On is refused while a required field is missing; off never is. | |
| purpose | No | What the payer must write as the purpose. Has to carry {invoice} — a transfer that does not name its bill arrives as a sum nobody can place. Defaults to 'Invoice {invoice}'. | |
| bankName | No | The bank's name and address. | |
| minimumUsd | No | The smallest bill that may be paid by transfer, in USD — correspondent fees eat a small one. Left out there is NO floor, which is the cleared state and not zero; a customer under it is offered the other ways to pay and told why. | |
| beneficiary | No | Who the money is sent to — the account holder's name as the bank has it. | |
| daysToArrive | No | How many days a wire is given to arrive, 1 to 60. The period stays open that long. Left out, the stored number is kept (7 to start with). | |
| accountCurrency | No | The account's OWN currency, e.g. 'AMD'. Bills stay in USD; this is what the receiving bank converts into. | |
| intermediaryBank | No | The intermediary bank's name, where one is needed. | |
| intermediarySwift | No | The intermediary bank's SWIFT/BIC. | |
| intermediaryAccount | No | Our account at the intermediary bank. |
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.
Administrators only: what was done to one company and by whom — created, plan changed, period extended by hand, credited, suspended, resumed, erased — newest first, up to a hundred entries, each with the reason that was written down at the time. This is the answer to 'why is this company on a period nobody paid for'. The actor is our own operator, and is named because an entry without one answers nothing. A company living on another machine of the fleet is not here: the answer then names the machine to ask.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The company's address — 'acme' in acme.kaiku.tech. |
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.
Administrators only: every company on the installation — its plan, what state it is in (trial, active, over-limit, suspended…), when what it paid for runs out, how many days are left, what it is using against what it may use, and its balance. Ask with endingInDays to get only the ones running out that soon, which is how 'whose trial ends this week' is answered in one call. 'attention' is the console's own short list of rows somebody has to look at. A meter reading null means the machine holding that company was not asked, not that it is idle. Owners are left out unless withOwners is true, and an e-mail address is never returned.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Only the company at this address ('acme' in acme.kaiku.tech). | |
| status | No | Only companies in this state: 'trial', 'active', 'free', 'over-limit', 'expired', 'suspended'. | |
| withOwners | No | Include who owns each company — username and display name, never an e-mail. Off by default: this is a statistics surface, and a list of customers with names on it is a customer list. | |
| endingInDays | No | Only companies whose paid-for period ends within this many days. 0 means already run out. |
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.
Answer a question that was put to you on an issue, by choosing one of its options. Only the person the question was addressed to may answer it; answering again with a different option changes the answer and says so in the thread. A question whose deadline already passed can still be answered — that replaces whatever the deadline took, and the change is recorded. The answer is written into the thread as an ordinary comment and the asker is told.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Words of your own beside the option — a qualification, not the answer itself ('Postgres, but only after the migration lands'). Ignored when the asker switched free text off; check 'allowsFreeText' on the question. | |
| option | Yes | Which option to choose, counted from 0 in the order they were offered. | |
| questionId | Yes | The question's id, as returned by list_issue_questions or ask_issue_question. |
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.
Ask one person a question with pre-written answer options, in an issue's thread — the way to get a decision that does not get lost in the comment stream. The question appears as an ordinary comment (so every Jira-speaking reader sees it) and is tracked separately: the person you ask sees it counted in their Questions list until they answer. It does not wait for ever — give 'defaultOption' and the deadline takes it if nobody answers, so a blocked run can go on. Requires permission to comment in that project. NOTE: this is not the bgs 'ask_question' tool, which is the background-agent ledger — this one is a question to a person on a PM issue.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Who to ask: the username, which list_users hands you ready-made — never the display name. They must be able to see this project, and it cannot be you. | |
| key | Yes | Issue key, e.g. 'UK-1'. | |
| options | Yes | The answer options, in the order to offer them: at least 2, at most 8, each a short label rather than a paragraph. Fewer than two is not a question with options — that is a comment. | |
| question | Yes | The question itself. Keep it to what the options answer. | |
| ttlHours | No | How long to wait, in hours. Omitted is 48 (two days). 0 means no deadline at all — the question waits until somebody answers it, which is rarely what an agent wants. | |
| allowFreeText | No | Whether the answerer may add words of their own beside the option they choose. Defaults to true. Set false when the answer has to be machine-comparable and nothing else. | |
| defaultOption | No | Which option to take if nobody answers before the deadline, counted from 0. Give one whenever there is a safe assumption — it is what lets you carry on rather than stall. Omit it when no option is safe to assume: then the deadline only stops the waiting and decides nothing. |
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.
Create an issue in a project visible to this token. Returns the new issue key. Requires permission to create issues in that project. Answers with 'notified' (who this actually reaches) and 'unresolvedMentions' (what looked like a mention and reached nobody, each with a reason) — a wrong handle is stored as written and never refused, so that list is the only sign it did not land.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Issue type name, e.g. 'Task', 'Bug', 'Story', 'Epic'. Defaults to 'Task'. | |
| labels | No | Labels to set, space or comma separated. | |
| dueDate | No | The day this is due, as YYYY-MM-DD. A calendar day, not a timestamp — do not send a time or a zone. | |
| summary | Yes | Issue summary (title). | |
| assignee | No | Assignee username or email. Omit to leave unassigned. | |
| priority | No | Priority name, e.g. 'High'. | |
| parentKey | No | Parent issue key, to create this as a child/sub-task. | |
| projectKey | Yes | Project key, e.g. 'UK'. | |
| description | No | Issue description. Markdown is kept as written, and carries $…$ / $$…$$ LaTeX formulas and [~username] mentions (the username, which list_users hands you ready-made — never the display name). |
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 that permission is required, returns the new issue key, and details a subtle behavior: unresolved mentions are not refused but stored as written, with 'unresolvedMentions' being the only signal. This goes well beyond a simple 'creates an issue' and provides crucial insight into how the tool handles edge cases.
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 approximately 70 words, consisting of four concise sentences. It front-loads the core purpose and return value, then covers permission and the mention behavior. There is no redundant or filler language; every sentence contributes to the agent's understanding.
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 (9 parameters, no output schema), the description is fairly complete. It mentions the return values (issue key, notified, unresolvedMentions), permission requirements, and the mention behavior. While it doesn't cover error cases or rate limits, the combination of schema descriptions and this behavioral context is sufficient for correct invocation. The missing details are minor compared to what is provided.
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 has 100% description coverage, so the baseline is 3. The description adds value by explaining the behavior around mentions and handles, which directly impacts parameters like assignee and description. It clarifies that a wrong handle is stored as written and never refused, a nuance not present in the schema. This enhances understanding of parameter usage beyond the schema's basic 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 states a specific verb ('Create'), a resource ('issue'), and a scope ('in a project visible to this token'). It distinguishes from siblings like update_issue and create_project, making it clear this tool is for creating new issues. The mention of returning the new issue key further clarifies 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 clearly indicates the tool's purpose, which implicitly suggests when to use it (to create a new issue). However, it does not explicitly state when not to use it or name alternatives like update_issue or set_issue_fields for modifying existing issues. There is no explicit guidance on selecting between siblings, so it relies on the reader to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Administrators only: create a project — a new key, a starter board, and its own wiki space, led by you unless you name someone else. The key is yours to choose and is never invented for you: one already taken is refused, naming the project holding it, rather than quietly becoming KEY2 — the key shows in every issue key, link and commit, and renaming it later costs more than creating the project did. Calling it again with the same key and name returns that same project with created:false, so a retry after a lost answer cannot make a second project. Deleting one is not offered here: that is a decision a person makes looking at what is inside. Who may: an administrator of this workspace, or — for a subproject — the lead of the parent, since it hands over their own project's people.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Project key, 2–10 characters: a letter followed by letters or digits, e.g. 'BGS'. Uppercased. | |
| lead | No | Username or email of the project lead. Defaults to you — a project with no lead is one nobody can configure: export, colour, the bgs connection and access grants all need a lead or an admin. | |
| name | Yes | Project name, e.g. 'Background agents'. | |
| parentKey | No | Key of the project this one is a subproject of. Everybody who may reach the parent may reach this project too, in the role they hold there — so add only the people the parent does not already have. Leave it out for a project of its own. One level: a subproject cannot have subprojects. The key here is still an ordinary key ('KYCB2B', not 'KYC-B2B'), because it is what every issue key is built from. | |
| description | No | What the project is for. Markdown. | |
| projectTypeKey | No | Jira project type: 'software' (the default), 'business' or 'service_desk'. |
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.
Add a rule to a project: when an issue enters 'status', append 'template' to its description. A rule appends its checklist to an issue's description when the issue ENTERS the rule's state — from the board, the Jira API or update_issue alike. The block starts with a hidden marker line '[//]: # (pm-rule:)'; while that line is in the description, entering the state again adds nothing (the journal says 'alreadyThere'). A [~username] in the template is a mention: that person is notified when the checklist lands. A checklist that would make the description too long is not added and the journal says 'tooLong'; the move itself still happens. A rule with action 'agent' is a DUTY instead: it says which issues may be handed to an agent role (agentRole, e.g. 'product') and what the agent may do with them. Its 'template' is then the INSTRUCTION — what doing such an issue means in this project — and nothing is appended anywhere. A duty may have no state (pass an empty 'status'): then an issue is handed only by a person. agentActions is a list from: describe, subtasks, ask, wiki, report, support. agentFields names the fields it may set: priority, labels, duedate, or the project's own fields by name. doneStatus is the state it moves the issue to when done — never a finished one. capUsd raises what one task may cost, up to 5 dollars. Commenting is always allowed; finishing, deleting, reassigning and anything outside the issue never are. Saving or switching on a duty makes it yours: it runs on your behalf and access, and is switched off if you lose the project. The state and the type are NAMES of this project's own (list_project_rules lists them); an unknown one is refused with the list. Project lead or admin only.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | What the rule is called, e.g. 'Document pack'. At most 120 characters. | |
| type | No | Only issues of this type, by name, e.g. 'Bug'. Leave out for any type. | |
| label | No | Only issues carrying this label (one word). Leave out for any label. | |
| action | No | 'checklist' (the default) or 'agent' for a duty. Fixed once the rule exists. | |
| capUsd | No | For a duty: what one task may cost, in dollars, when more than the ordinary ceiling is needed. At most 5. | |
| status | Yes | The state whose ENTRY fires the rule, by name, e.g. 'Ready for review'. For a duty taken only by hand, an empty string. | |
| enabled | No | Whether the rule is on from the start. Default true. | |
| template | Yes | The checklist, as Markdown: a '### Heading' per group, '- [ ] item' per line, two spaces of indent to nest an item under another, and [~username] on an item to name who does it. For a duty: the instruction. | |
| agentRole | No | For a duty: the agent role's key, e.g. 'product'. | |
| doneStatus | No | For a duty: the state it moves the issue to when done. Never a finished state. Leave out and it does not move the issue. | |
| projectKey | Yes | Project key, e.g. 'ONB'. | |
| agentFields | No | For a duty: the fields it may set, comma-separated — priority, labels, duedate, or a project field's name. | |
| agentActions | No | For a duty: what the agent may do beyond commenting, comma-separated — describe, subtasks, ask, wiki, report, support. |
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 thoroughly describes side effects (appending, marker line, deduplication, tooLong behavior), permissions (project lead or admin only), and duty-specific behavior (runs on your behalf, switched off if you lose the project). No behavioral aspect is left unstated.
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 lengthy but well-structured, starting with the core purpose and then elaborating on behavior. Every sentence carries useful information for a complex tool with 13 parameters. While it could be trimmed slightly, the length is justified by the tool's complexity.
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 (13 parameters, no output schema, no annotations), the description is exceptionally complete. It covers permissions, edge cases, duty vs checklist behavior, and parameter constraints. An agent could confidently invoke this tool correctly based on the description alone.
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. The description adds meaningful semantic value beyond the schema by explaining how parameters interact (e.g., capUsd limit, doneStatus never finished, agentActions list) and clarifying the template format for both checklist and duty. It does not merely repeat 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 states a specific verb-resource pair: 'Add a rule to a project' and explains exactly what the rule does (appends a template when an issue enters a status). It also distinguishes the two rule types (checklist vs duty), clarifying its purpose beyond just the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains the context of when a rule fires and the distinction between checklist and duty, guiding parameter selection. However, it does not explicitly mention sibling tools like update_project_rule or state when not to use this tool, though it's implied that creation is for new rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a wiki page from Markdown in a space you can write to. Hangs off the space home page unless you name a parent (by 'parentId', or by 'parentTitle' within the same space). Returns the new page id and its URL. Mention someone as @Their Name — on a wiki page that is the form that notifies, not the [~username] used in issues; link another page as text or text. Answers with 'notified' (who this actually reaches) and 'unresolvedMentions' (what looked like a mention and reached nobody, each with a reason) — a wrong handle is stored as written and never refused, so that list is the only sign it did not land.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Page title. Must be unique within the space — the title is how pages are addressed here. | |
| labels | No | Labels to set, space or comma separated. | |
| markdown | No | Page body as Markdown, which also carries $…$ / $$…$$ LaTeX formulas and the wiki's macros on a line of their own — {toc}, {children}, {info} … {info}, {expand:title=…} … {expand}. | |
| parentId | No | Parent page id. Omit to hang the page off the space home page. | |
| spaceKey | Yes | Space key, e.g. 'PM'. Every project has exactly one space, keyed like the project. | |
| parentTitle | No | Parent page title, as an alternative to 'parentId'. Must be a page in the same space. |
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.
Decide what a held or failed letter to the support address is. 'release' files it as if it had just arrived, past the spam filter and the limits: it joins the request it proves it answers, or opens a new one (and the sender gets the usual acknowledgement). 'dismiss' says it is not a request; its files are dropped and the row is deleted with the other unfiled letters after 30 days. Requires full write access to the support project.
| Name | Required | Description | Default |
|---|---|---|---|
| decision | Yes | 'release' or 'dismiss'. | |
| letterId | Yes | The letter's id, from list_support_letters. |
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.
Remove one agent-usage record from an issue, by the id that get_agent_usage returns. For correcting a record's numbers, re-send it with report_agent_usage instead — the same source + externalId updates in place. Requires permission to edit the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Record id, as returned by get_agent_usage. | |
| key | Yes | Issue key, e.g. 'UK-1'. |
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.
Remove a file from an issue, by 'filename' or by attachment 'id' — both come back from get_issue. Requires permission to edit issues in that project.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Attachment id, as listed by get_issue. An alternative to 'filename'. | |
| key | Yes | Issue key, e.g. 'UK-1'. | |
| filename | No | File name to remove, as listed by get_issue. |
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.
Remove a column from a project. Answers with how many issues lost a value, because that number is what the decision was about — the issues themselves are untouched. Project lead or admin only.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Field name, e.g. 'Provider'. | |
| projectKey | Yes | Project key, e.g. 'CRM'. |
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.
Remove a project rule, by its id from list_project_rules. Checklists it already added stay in their issues; its journal goes with it. To stop it for a while instead, update_project_rule with enabled=false. Project lead or admin only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The rule's id, from list_project_rules. | |
| projectKey | Yes | Project key, e.g. 'ONB'. |
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.
Remove a file from a wiki page, by its 'filename' as listed by get_wiki_page. Identify the page by 'pageId', or by 'spaceKey' + 'title'. References to it in the page body are left alone — they simply stop resolving, so tidy the body too if it named the file. Requires permission to edit the page.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Exact page title, when identifying the page by title. | |
| pageId | No | Page id (as returned by search_wiki). | |
| filename | Yes | File name to remove, as listed by get_wiki_page. | |
| spaceKey | No | Space key, when identifying the page by title. |
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.
Delete a wiki page. Identify it by 'id', or by 'spaceKey' + 'title'. A page with children takes its whole subtree with it, so that is refused unless you pass includeChildren: true — the answer names what would go. The space home page can never be deleted. Requires permission to edit the wiki.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Page id (as returned by search_wiki). | |
| title | No | Exact page title, when identifying the page by title. | |
| spaceKey | No | Space key, when identifying the page by title. | |
| includeChildren | No | Delete the page's descendants along with it. Off by default. |
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.
What background-agent runs have cost an issue (local or mirrored/upstream): one record per run (tokens by kind, machine time, agent/model/host) plus the totals. A null metric means nobody reported it — which is not the same as zero, so 'reporting' says how many records carried each metric.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. |
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.
Read one file attached to an issue — its bytes, base64-encoded — by the issue key and the 'filename' as get_issue lists it. The bytes travel as text through the conversation and cost roughly a third more than the file itself, so there is a size ceiling; the pm-files MCP server saves a file to a path instead, without spending the conversation on it. Reading needs only permission to see the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| filename | Yes | File name, as listed by get_issue. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that bytes travel as text, that there is a size ceiling, that the encoding costs roughly a third more, and that reading requires only issue-view permission. It doesn't specify the exact size limit or error behavior, but the core behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: what it does, cost/size trade-off, and permission. The key operation is front-loaded, and there is no redundant repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with no output schema, the description covers the return format (base64), the source of the filename, the alternative for large files, and the required permission. 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 the baseline is 3. The description adds value by saying the filename must be exactly as listed by get_issue, which clarifies an important parameter relationship beyond the schema's generic 'File name' 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?
The description states a specific verb ('Read') and resource ('one file attached to an issue'), and specifies the exact output (bytes, base64-encoded). It clearly differentiates from sibling tools like add_attachment, delete_attachment, and get_issue.
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: call by issue key and filename, only needs issue-view permission, and mentions the pm-files MCP server as an alternative when saving to a path is preferable. It doesn't explicitly state when not to use this tool beyond size considerations, but the alternative is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The files one merge request, pull request or commit touches, with their diffs. Large diffs arrive cut.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Which repository, as 'group/repo'. Omit when only one is open. | |
| change | Yes | The merge request or pull request number ('!12', '#12' or '12'), or a commit's hash. |
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.
Read the discussion on an issue, oldest first. Without 'startAt' you get the END of the thread — the most recent 'limit' comments — because catching up means reading the latest, not the first ever written; 'earlier' says how many stand before the page you got, and 'startAt' walks back through them. Each 'body' comes back exactly as written, which is also the text update_comment's 'edits' are matched against. A reply carries 'replyTo', the id of the comment it answers (null otherwise) — pass the same id to add_comment's 'replyTo' to answer one. Comments that were deleted are not listed. Needs only permission to see the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| limit | No | How many comments to return (default 20, max 100). | |
| startAt | No | Where to start, counted from the OLDEST comment as 0. Omit for the most recent page; pass 'startAt' - 'limit' from a previous answer to step back one page. |
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.
Get one issue by key (e.g. 'UK-1') if it is visible to this token, including its description, status, assignee, labels, sub-tasks, the issues it is linked to and the wiki pages linked to it. 'comments' is a COUNT, not the text — read the thread itself with get_comments whenever it is not zero: decisions, the map of what is attached and how to run the thing are often written there rather than in the description.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. |
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.
A project rule's journal, newest first: each time an issue entered the rule's state and matched its conditions — which issue, who moved it, and the outcome: 'applied' (checklist added), 'alreadyThere' (its marker line was already in the description, nothing added) or 'tooLong' (the description would have been too long, nothing added); for a duty, 'handed' (the issue went to its agent), 'busy' (an agent already had it), 'tooMany' (the duty's fifty a day were used up) or 'refused' with a 'reason' (agent_off, agent_budget, …), and 'ownerLost' when the duty was switched off because its owner lost the project. The place to look when a checklist did not appear or an agent did not take an issue. Any member may read it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The rule's id, from list_project_rules. | |
| limit | No | How many lines, newest first (default 20, max 100). | |
| projectKey | Yes | Project key, e.g. 'ONB'. |
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.
Read one letter to the support address whole — the quoted thread and the signature that the request's comment leaves out, the HTML part as text, and the headers. 'letterId' comes from list_support_letters or from get_support_request's messages. A letter in a request is readable by whoever can read that issue; any other only by the support project's full members.
| Name | Required | Description | Default |
|---|---|---|---|
| letterId | Yes | The letter's id. |
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.
Read who is behind a support request: the requester's name and email, whether they asked signed in (and from which workspace), their client version, what the product knew when they asked from inside it ('context': the screen, the client, the last refusal the server gave them with its request id), and which comments of the issue the requester can see ('messages', by comment id and direction; 'autoRule' names the rule when the desk's automatic answer wrote it rather than a person, 'autoWording' says whether the model worded it or the template went). Every other comment on the issue is internal — the requester never sees it. Answers found=false for an issue that is not a support request.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key of the request, e.g. 'SUPPORT-12'. |
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.
Read one file attached to a wiki page — its bytes, base64-encoded — identifying the page by 'pageId' or by 'spaceKey' + 'title' and the file by 'filename' as get_wiki_page lists it. This is how a file is copied from one page to another: read it here, write it with add_wiki_attachment. The bytes travel as text through the conversation and cost roughly a third more than the file itself, so there is a size ceiling; for anything larger — or for putting the file on disk — the pm-files MCP server saves it to a path instead. Reading needs only permission to see the page.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Exact page title, when identifying the page by title. | |
| pageId | No | Page id (as returned by search_wiki). | |
| filename | Yes | File name, as listed by get_wiki_page. | |
| spaceKey | No | Space key, when identifying the page by title. |
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 the return format (base64-encoded bytes), the overhead of traveling as text (roughly a third more), and the resulting size ceiling, plus the permission requirement. This goes well beyond the schema and gives the agent operational awareness. A 5 would require even more detail, such as exact error behaviors, but the current disclosure is strong.
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 dense with information: purpose+identification, use case+counterpart, and size/alternative+permission. The primary action is front-loaded. It could be trimmed slightly, but no sentence is wasted and the structure flows logically from what→how→when.
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 correctly explains what the tool returns (base64-encoded bytes). It covers the identification methods, the primary use case, the size limitation and alternative, and the permission requirement. For a read-only retrieval tool with four parameters, this is complete — 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 each parameter is already documented. The description adds the important rule that the page can be identified by either pageId or by spaceKey+title (implying mutual exclusivity), which the schema does not state. It also clarifies that filename follows the listing from get_wiki_page. This adds meaning beyond the schema, though it doesn't delve into formats or defaults further, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Read), a precise resource (one file attached to a wiki page), and even enumerates the identification methods (pageId or spaceKey+title, filename). It clearly distinguishes from the sibling get_wiki_page (which lists files) and add_wiki_attachment (which writes), so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes a concrete use case (copying a file between pages) and names the exact counterpart tool (add_wiki_attachment) for the write half. It also gives an exclusion condition (anything larger, or for disk) and points to the pm-files MCP server as the alternative, plus notes the only prerequisite (permission to see the page). No guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one wiki page by id, or by space key + title, if it is visible to this token. Returns the page text, its labels, its parent and child pages, its comments, and the issues linked to it. Pass withMarkdown: true when you intend to edit it — you then get the page's Markdown source to change and hand back to update_wiki_page, and each comment's own Markdown, version and anchor for update_wiki_comment. A large page is read a part at a time: 'outline' lists its headings and how big each section is, then 'section' returns one of them (or 'offset'/'limit' a run of lines), and update_wiki_page's 'edits' changes just the words you mean without sending the page back.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Page id (as returned by search_wiki). | |
| limit | No | How many lines to return from 'offset' (default 200). | |
| title | No | Exact page title, when looking the page up by title. | |
| offset | No | Return only the Markdown source from this 1-based line on — for a page without headings to navigate by. Pair with 'limit'. | |
| outline | No | Return the page's table of contents instead of its body: per heading its level, text, anchor, the 1-based lines its section spans in the Markdown source, and its size in characters. Start here on a large page. | |
| section | No | Return only this section's Markdown — its heading line down to the next heading of the same or a higher level, subsections included. Name it by its anchor (as 'outline' gives it: the id a {toc} entry links to) or by its heading text. | |
| spaceKey | No | Space key, when looking the page up by title. | |
| withRelated | No | With 'outline', 'section' or 'offset': also return the page's children, attachments, comments and linked issues, which a partial read otherwise leaves out. | |
| withMarkdown | No | Return the Markdown source ('markdown') instead of the plain text — what to edit and pass back to update_wiki_page, and, for each comment, to update_wiki_comment. Off by default: reading costs less as text. |
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.
Link two issues: link_issues('PM-419', 'PM-417', 'is blocked by') records that PM-419 is blocked by PM-417. 'type' is the PHRASE, said as a person says it — 'blocks', 'is blocked by', 'duplicates', 'is duplicated by', 'clones', 'relates to' — so the direction is in the words and the arguments cannot disagree; a bare type name ('Blocks') points outward, as it does in Jira. A phrase this workspace does not have is REFUSED and the ones it does have are named, rather than quietly becoming 'relates to'. The link then shows on both issues (get_issue returns 'links'), and linking the same pair the same way again changes nothing. Requires permission to edit BOTH issues — a link is a change to the issue at each end.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | The issue at the other end, e.g. 'PM-417'. | |
| from | Yes | The issue the phrase is said about, e.g. 'PM-419'. | |
| type | Yes | How 'from' relates to 'to', in words: 'blocks', 'is blocked by', 'duplicates', 'clones', 'relates to'. Whatever this workspace's link types call themselves — a refusal lists them. |
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.
Link a wiki page to an issue. The link then shows on both the issue and the page, and survives the page being renamed or moved. Identify the page by 'pageId', or by 'spaceKey' + 'title'. Linking the same page again updates that link instead of adding a second one. Requires permission to edit the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Exact page title, when identifying the page by title. | |
| pageId | No | Page id (as returned by search_wiki). | |
| issueKey | Yes | Issue key, e.g. 'UK-1'. | |
| spaceKey | No | Space key, when identifying the page by title. | |
| relationship | No | How the page relates to the issue, free text — e.g. 'documentation' (the default), 'specification', 'design'. |
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.
List a directory of a repository connected to a project. Only repositories whose owners opened them to agents can be read.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory inside the repository. Omit for its root. | |
| repo | No | Which repository, as 'group/repo'. Its last segment alone is enough when unambiguous; omit it when only one is open. | |
| reference | No | Branch, tag or commit. Omit for the default branch. |
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.
List the credentials attached to an issue or a wiki page that this token may read — names and who attached them, never the values. Pass issueKey or pageId. Use reveal_credential to read one value, and only when you are about to use it.
| Name | Required | Description | Default |
|---|---|---|---|
| pageId | No | Wiki page id. | |
| issueKey | No | Issue key, e.g. 'UK-1'. |
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.
Questions with answer options, in either direction: what is waiting on YOU to answer (role='to_me'), what YOU asked and are waiting on somebody for (role='asked'), or everything on one issue. This is how you find out whether the question you asked has been answered — poll it, since ask_issue_question does not wait. With no 'key' the default is role='to_me'; with a 'key' it is every question on that issue. Open ones by default; pass state='all' for the answered, withdrawn and expired ones too.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Limit to one issue, e.g. 'UK-1'. Omit to look across every project this token can reach. | |
| from | No | 'agent' for only what an agent put to somebody (a resolution, PM-602), 'people' for only what a person asked. Omit for both. | |
| role | No | Whose questions: 'to_me' (waiting on you to answer), 'asked' (you asked them, and you are waiting), or 'any'. Defaults to 'to_me' with no key, and to 'any' when a key is given. | |
| limit | No | How many to return (default 20, max 100). | |
| state | No | 'open' (the default — still waiting on somebody) or 'all', which adds the answered, the withdrawn and the expired (the deadline passed with no default and no answer). | open |
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.
List the external MCP connections configured for a project. Auth tokens are never returned (only whether one is set).
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | Project key, e.g. 'UK'. |
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.
The columns a project keeps about its issues: name, kind, and a list's options with their colours. Also the customfield_… name each one answers to, for searching by JQL. Any member may read them.
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | Project key, e.g. 'CRM'. |
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.
A project's rules: when an issue enters a state, a checklist from a template is appended to its description. A rule appends its checklist to an issue's description when the issue ENTERS the rule's state — from the board, the Jira API or update_issue alike. The block starts with a hidden marker line '[//]: # (pm-rule:)'; while that line is in the description, entering the state again adds nothing (the journal says 'alreadyThere'). A [~username] in the template is a mention: that person is notified when the checklist lands. A checklist that would make the description too long is not added and the journal says 'tooLong'; the move itself still happens. A rule with action 'agent' is a DUTY instead: it says which issues may be handed to an agent role (agentRole, e.g. 'product') and what the agent may do with them. Its 'template' is then the INSTRUCTION — what doing such an issue means in this project — and nothing is appended anywhere. A duty may have no state (pass an empty 'status'): then an issue is handed only by a person. agentActions is a list from: describe, subtasks, ask, wiki, report, support. agentFields names the fields it may set: priority, labels, duedate, or the project's own fields by name. doneStatus is the state it moves the issue to when done — never a finished one. capUsd raises what one task may cost, up to 5 dollars. Commenting is always allowed; finishing, deleting, reassigning and anything outside the issue never are. Saving or switching on a duty makes it yours: it runs on your behalf and access, and is switched off if you lose the project. Answers with each rule's id (the other rule tools take it), action, state, conditions (type, label — null means any), template and whether it is on, and for a duty its 'agent' part; with the state and type names a rule may use, the agent roles, actions and fields a duty may name where agents are on; and 'canEdit'. Any member may read them.
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | Project key, e.g. 'ONB'. |
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 read permissions, the exact contents of the response, and rich domain semantics (rule markers, idempotency, duty behavior, 'tooLong' outcomes) that an agent must understand to interpret results correctly. It also implies non-mutating behavior via 'Any member may read them.'
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 information-dense and every block of detail contributes to understanding rule semantics, but it is a single long unstructured paragraph. It is not front-loaded with the tool's list purpose, and the volume of domain explanation makes it heavier than necessary for a simple read/list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain return values, and it does so thoroughly: rule ids, action, state, conditions, template, enabled flag, duty agent details, allowed values, and canEdit. It also covers permission and key behavioral rules, making it complete enough for an agent to invoke the tool and interpret its 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 description coverage is 100%, so the projectKey parameter is already documented. The description adds no parameter-specific meaning beyond clarifying the tool concerns 'A project's rules,' which is the baseline expected with fully covered 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 indicates a read operation by saying it 'Answers with each rule's id... and canEdit' and 'Any member may read them.' It distinguishes the tool from rule-modifying siblings by emphasizing that its output supplies the IDs other rule tools consume, though it never crisply states 'Lists project rules' at the start.
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 the main use case: retrieve rule data and IDs needed by 'the other rule tools.' It gives permission context ('Any member may read them') but does not explicitly state when to prefer this over related tools like get_project_rule_runs, or 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.
List the projects visible to this token (a project-scoped token sees only its project). A project with a 'parent' is a subproject of that one: it has its own issues, board and wiki, and shares only who may reach it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
List letters to the support address that did not become part of a request: 'held' (looked like spam, or too many at once from one address or on one request), 'failed' (we could not file them), 'ignored' (an autoresponder, a bounce, a mailing list, our own letter), 'dismissed'. Without 'state', held and failed — the ones waiting for a person. Each has an id, the reason, the sender, the subject and the file names. Only a full member of the support project may read them: they are strangers' words.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | One of 'held', 'failed', 'ignored', 'dismissed'. Omit for held and failed. |
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.
The support desk's queue: open requests, the most urgent first — overdue, then due soonest, then those waiting on their requester. Each item says whose turn it is ('clock.turn': 'first' = nobody has answered yet, 'reply' = the requester wrote again, 'requester' = we answered last and the clock is stopped), since when it has waited, the working hours waited, when the answer is due and whether it is 'onTime', 'dueSoon' or 'overdue'; plus the assignee. 'numbers' has the current counts and, over the last 30 days, the median time to a first human answer and to resolution (in working hours — weekdays only) and the share answered within the promise. An automatic acknowledgement or automatic answer is never counted as an answer; 'numbers.auto' says how many requests the automatic answer got, how many were then resolved with no human reply and no further word from the requester ('settled'), and how many requesters wrote again after it ('askedAgain') — per rule too. An item's 'autoRule' is set when the request got an automatic answer. Readable by anybody who can read the support project.
| Name | Required | Description | Default |
|---|---|---|---|
| who | No | 'all' (default), 'mine' (assigned to you) or 'unassigned'. |
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.
The tracks a project is cut into: a track is a LABEL the project declared meaningful — a play, a campaign, a rollout — and work joins one by carrying that label. A track has no key of its own; its issues keep the project's key, which is what makes it a different thing from a subproject (a separate project, see create_project's parentKey). Any member may read them.
| Name | Required | Description | Default |
|---|---|---|---|
| projectKey | Yes | Project key, e.g. 'TH'. |
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.
List the people you can assign work to or mention: the members of the projects this token can see. Optionally filter by free text (username, display name or email) or narrow to one project. Mention someone in a description or comment as [~username] — a mention matches the username, never the display name — and pass the same username (or the email) as 'assignee'.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Free text to match in username, display name or email. | |
| limit | No | Max users to return (default 50, max 200). | |
| projectKey | No | Restrict to members of this project key (must be visible to the token). | |
| includeInactive | No | Include deactivated accounts, which can be neither assigned nor mentioned. Off by default. |
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.
List the wiki spaces visible to this token. Every project has exactly one space, keyed like the project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that only spaces visible to the token are listed (a key behavioral trait), and it adds the fact that each project has exactly one space keyed like the project. This is useful context beyond a trivial list call, but it doesn't mention response format or pagination.
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 with no waste. It front-loads the core purpose and then adds a helpful relationship note. Everything 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 zero-parameter list tool, the description is complete. It covers what it lists, the token scoping, and a key invariant (one space per project). An output schema is absent, but a list of spaces is predictable; the description covers the essentials.
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, and schema coverage is 100% (empty object), so the description doesn't need to add parameter details. It still provides useful context about the relationship between projects and spaces, which is helpful for understanding the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb and resource ('List the wiki spaces') with a scoping detail ('visible to this token'). It doesn't explicitly distinguish from siblings like search_wiki or get_wiki_page, but the purpose is clear enough.
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?
Implies usage when you need to enumerate the wiki spaces available to the token, but doesn't provide explicit when-to-use vs alternatives. The scoping to token is useful context, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move an issue into another project, taking its comments, history, attachments, links and sub-tasks with it. The key does NOT change: 'PM-12' stays 'PM-12' wherever it lives, so every existing link and branch name goes on working. Call it with apply=false first (the default): the answer says what the move would cost — values in columns the target project does not have are LOST, the sprint is cleared, and a secret attached to the issue becomes readable by the target project's lead. Refuses when the target has no state by the issue's status name; say what that state becomes with 'statuses'. A sub-task cannot move on its own — move its parent. Needs full write access in BOTH projects.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The issue to move, e.g. 'PM-12'. | |
| apply | No | false (the default) answers what the move would do and changes nothing. true does it. | |
| statuses | No | What each source status becomes in the target project, as 'In Review=Review, Blocked=On hold'. Only needed for states the target does not already have under the same name. | |
| toProject | Yes | Project key to move it into, e.g. 'CRM'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description alone discloses side effects and risks: values in missing columns are LOST, sprint is cleared, secrets become readable by the target lead, apply=false changes nothing, and full write access is required in both projects. This is exemplary behavioral disclosure 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 but every sentence carries essential information, and the core action is front-loaded. It could be slightly improved with structural separation of the warning clauses, but for a complex mutation tool the length is justified.
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 operation's complexity and lack of an output schema, the description covers purpose, dry-run flow, data-loss risks, auth requirements, and the sub-task limitation. The only notable gap is that it doesn't describe the shape of the dry-run 'answer' result an agent would need to parse.
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 what apply=false does ('answers what the move would do and changes nothing'), giving the statuses mapping format, and anchoring key/toProject with concrete examples like 'PM-12' and 'CRM'.
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—'Move an issue into another project'—and immediately lists what travels with it (comments, history, attachments, links, sub-tasks). This clearly separates it from create/update tools and leaves no ambiguity about what the operation 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?
It gives explicit procedural guidance: 'Call it with apply=false first (the default)' and explains the dry-run purpose. It also names a refusal condition and its remedy ('Refuses when the target has no state... say what that state becomes with statuses') and states a critical constraint ('A sub-task cannot move on its own — move its parent').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one file from a repository connected to a project. A long file arrives cut and says so; generated and binary files are not read.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The file's path inside the repository, e.g. 'src/app/main.ts'. Not a URL. | |
| repo | No | Which repository, as 'group/repo'. Omit when only one is open. | |
| reference | No | Branch, tag or commit. Omit for the default branch. |
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 two non-obvious behaviors: long files are cut off and the tool reports that, and generated/binary files are skipped. It doesn't detail return format or error handling, but the key behavioral surprises are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core action is front-loaded, and each additional clause adds meaningful constraints or 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 simple three-parameter read tool with no output schema, this covers the essential scope, truncation behavior, and file-type exclusions. It doesn't explain the overall return format, but an agent has enough context to invoke it correctly. A small gap is the lack of any error-handling or permissions context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds general behavior (file can be truncated, certain files excluded) but no parameter-specific semantics beyond what the schema already 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 opens with 'Read one file from a repository connected to a project,' a specific verb and resource. The singular 'one file' distinguishes it from siblings like list_code and search_code, which cover browsing or searching.
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 the tool: when you want one file's contents. It also states exclusions ('generated and binary files are not read'), but it doesn't explicitly name alternative tools or provide explicit when-to-use versus 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.
Undeclare a track. THE LABEL STAYS ON THE WORK: what goes is the declaration, so the issues keep their tag and declaring the track again brings exactly the same ones back. Nothing here can lose work — but the name, icon and place ARE lost, and the track's issues count as 'outside every track' afterwards. For a track that is merely finished, archive it instead: set_track with archived=true. Needs permission to write in the project.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | The track's tag, e.g. 'cherry-orchard'. | |
| projectKey | Yes | Project key, e.g. 'TH'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses what is preserved (issues, tags, labels), what is lost (name, icon, place), the reversible nature of re-declaring, and the post-condition that issues count as outside every track. This is unusually transparent for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then builds out the behavioral caveats in a logical order. Every sentence earns its place: purpose, preservation/loss semantics, alternative route, and permission. No filler or repetition is present.
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 only two fully documented parameters and no output schema, this description covers everything an agent needs: what the action does, what side effects occur, when not to use it, and what permission is required. The absence of a return-value description is not a gap because no output schema exists and the operation's effects are fully described.
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 input schema already documents both tag and projectKey with examples. The description adds no parameter-specific meaning beyond reinforcing that the track is identified by these values, which is sufficient given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening phrase 'Undeclare a track' gives a specific verb and resource, and the description immediately distinguishes this from removal or deletion by emphasizing that the label stays on the work. It also contrasts with the sibling set_track by positioning this as the opposite action. An agent can tell what this tool is for without inspecting other definitions.
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 the alternative: 'For a track that is merely finished, archive it instead: set_track with archived=true.' This gives a concrete branching condition and names the sibling to use instead. It also adds the permission requirement, making the invocation context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write to the person who opened a support request. The text becomes a comment the requester can read on their page and is emailed to them — unlike add_comment, which is always internal and never reaches the requester. Write it to the customer, in their language (get_support_request says which). Requires full write access to the support project. Answers with the comment id and whether the letter went ('emailed'; 'emailError' when it failed — the reply is kept either way).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key of the request, e.g. 'SUPPORT-12'. | |
| body | Yes | What to tell the requester. Markdown is kept as written. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the text becomes a requester-readable comment, is emailed, requires full write access, and reports email success/failure with 'emailed' or 'emailError', including the note that the reply is kept either way.
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 every sentence earns its place: purpose, distinction from sibling, language guidance, permission requirement, and return behavior. The key behavioral contrast is front-loaded in the first sentence.
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 tool with no annotations and no output schema, the description fully covers what an agent needs: what to write, how it is delivered, permissions, language handling, and the response shape including failure behavior.
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 key and body fully. The description adds context about the body becoming a visible comment, but it does not add new parameter-level semantics beyond what the schema provides. 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 names a specific verb and resource: 'Write to the person who opened a support request.' It clearly distinguishes this from add_comment by explaining that replies are visible to and emailed to the requester, while add_comment is internal only.
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 contrasts reply_to_requester with add_comment, telling agents when to use this tool instead of the sibling: when the customer must see and receive the message. It also adds the language instruction and the write-access prerequisite, leaving no ambiguity about appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record what one agent run cost an issue (local or mirrored/upstream): tokens by kind and machine time. Re-sending the same 'source' + 'externalId' updates that record instead of adding a second one, so a retry never doubles the spend. Omit a metric you did not measure — omitted is 'not reported', which is different from zero. Requires permission to edit the issue.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| host | No | Which host it ran on. | |
| note | No | Short note, e.g. the outcome. | |
| agent | No | Which agent did the work, e.g. 'claude-code'. | |
| model | No | Which model it ran on, e.g. 'claude-opus-5'. | |
| runId | No | The run this record belongs to, when one run reports several records (different models or hosts). | |
| source | Yes | Who is reporting, e.g. 'bg-agent-api'. Idempotency is scoped to it. | |
| costUsd | No | Cost in USD, if you know the rates that applied. | |
| endedAt | No | When the run ended (ISO 8601). | |
| startedAt | No | When the run started (ISO 8601). | |
| externalId | Yes | Your own key for this record (usually the run id). Re-sending it updates the record. | |
| inputTokens | No | Input (prompt) tokens. | |
| agentSeconds | No | Wall-clock seconds the run took. Machine time, not a worklog. | |
| outputTokens | No | Output (completion) tokens. | |
| cacheReadTokens | No | Cache-read tokens. | |
| cacheWriteTokens | No | Cache-write tokens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does well: it discloses that re-sending the same source+externalId updates rather than duplicates, that omitted metrics mean 'not reported' rather than zero, and that edit permission on the issue is required. This meaningfully exposes the tool's mutation and idempotency behavior 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?
Four short sentences, each earning its place: purpose, idempotency, omission semantics, and permission. The most important information is front-loaded, and there is no filler or repetition of the schema.
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 16-parameter write tool with no annotations and no output schema, the description covers the critical call-time semantics: what is recorded, the upsert behavior, the omitted-vs-zero distinction, and required permission. It does not explain the 'local or mirrored/upstream' qualifier or describe what the tool returns, but the core behavior an agent needs to call it correctly is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds real semantic weight: it identifies source+externalId as the idempotency key, maps 'tokens by kind' to the token parameters, and clarifies that null/omitted metrics are not to be interpreted as zero. The description does not need to re-explain every field, but it highlights the non-obvious meanings.
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 a specific verb and resource: 'Record what one agent run cost an issue' and names the exact data categories collected (tokens by kind, machine time). This clearly distinguishes it from sibling tools like get_agent_usage and delete_agent_usage, which read or remove this data rather than report it.
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 practical guidance for retries and omission semantics, and states the edit-permission requirement. However, it never explicitly contrasts this tool with its read/delete siblings or states when an agent should choose get_agent_usage or delete_agent_usage instead. The intended usage is implied rather than explicitly framed against alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one credential's value, by the id from list_credentials. This is the same act as pressing reveal on the screen and carries the same cost: it is recorded against the token you are using, and the person who owns the secret can see that you read it. Call it when you are about to use the value, not to have it on hand. The answer is marked secret: do not copy it into a comment, a description, a merge request or a log.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Credential id, from list_credentials. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral implications: reading is recorded against the token, the owner can see the read, and the answer is marked secret with explicit instructions not to copy it. This goes beyond the action itself and addresses audit and secrecy concerns, which is critical for a credential 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 efficient: the core action and source are stated in the first sentence, followed by crucial behavioral context in two more concise sentences. No wasted words; every sentence adds necessary 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 simple tool with one parameter and no output schema, the description is complete. It explains what the tool does, when to use it, the behavioral consequences, and the secrecy handling. An agent has everything needed 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 schema already describes the only parameter (id) as 'Credential id, from list_credentials.' The description reinforces this source but adds no new meaning. Since schema coverage is 100%, the baseline of 3 is appropriate; the description doesn't need to compensate.
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 specific action: 'Read one credential's value, by the id from list_credentials.' It identifies the resource (credential value), the verb (read), and the source of the id, distinguishing it from siblings like list_credentials. It also implies a security-sensitive read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to call it: 'Call it when you are about to use the value, not to have it on hand.' It implies when not to call it (just for convenience) and notes the cost. However, it doesn't explicitly mention alternatives, though no real alternative exists for reading a credential value.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find where a string appears in the code of the repositories connected to a project, with the file, the line number and the lines around it. Only repositories whose owners opened them to agents are searched, and the answer says when what it searched was out of date.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Narrow to files whose path contains this, such as 'src/' or '.ts'. | |
| repo | No | Which repository, as 'group/repo'. Omit to search every repository open here. | |
| query | Yes | What to look for, taken literally unless regexp is set. A space is a space, not two terms. | |
| regexp | No | Read query as a regular expression. One with no literal in it may not finish in time. | |
| caseSensitive | No | Match case. Off by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses two useful behaviors: the search is limited to repositories whose owners have opened them to agents, and the response indicates when the searched data was out of date. However, it does not explicitly state that the tool is read-only (though implied), nor does it mention rate limits, pagination, or result 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 description is two sentences with no filler. It front-loads the core purpose ('Find where a string appears in the code') and then adds the important scope and freshness behaviors. 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?
No output schema exists, but the description explains the return format (file, line number, surrounding lines) and key contextual constraints (project repositories, agent-opened repos, staleness note). It lacks details about result ordering or limits, but the description is complete enough for an agent to understand what the tool does and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add meaning to parameters like path, repo, regexp, or caseSensitive beyond what the schema already provides. It mentions 'string' which maps to query, but no additional semantic detail is offered.
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: 'Find where a string appears in the code of the repositories connected to a project.' It also specifies the output format (file, line number, surrounding lines), which clearly distinguishes it from sibling tools like search_issues and search_wiki that target different resources.
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 a clear scope (search code in project repositories) and a constraint (only repos opened to agents), but it does not explicitly mention alternatives such as search_issues or search_wiki, nor does it say when not to use this tool. The use-case is implied rather than directly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the issues visible to this token, with a JQL query — the same JQL the Jira REST surface takes, read by the same parser. A query naming a field this tracker does not have is REFUSED and named, never run: it would match everything and read as an answer. Without jql, the shorthand arguments filter instead. Most recently created first unless the query says ORDER BY. Archived issues are left out unless the query names archived, and archivedLeftOut says how many matches that hid — an empty list with it is not "there are none".
| Name | Required | Description | Default |
|---|---|---|---|
| jql | No | A JQL query, e.g. `assignee = currentUser() AND statusCategory != Done ORDER BY updated DESC`. FIELDS: project, status, statuscategory, issuetype, type, priority, resolution, assignee, reporter, creator, key, issuekey, id, summary, description, sprint, parent, epic, labels, archived, agent, text, created, updated, duedate. OPERATORS: = != ~ !~ > >= < <=, IN (...), NOT IN (...), IS EMPTY, IS NOT EMPTY, combined with AND / OR, with parentheses around a sub-expression — `project = PM AND (status = Blocked OR priority = Highest)` — plus an optional trailing ORDER BY <field> [DESC]. `~` means contains (substring) and is the one to use for free text — `text` searches summary, description and comments. `>` `>=` `<` `<=` are for created/updated/duedate only, with absolute YYYY-MM-DD values: there are NO relative-date functions, so compute the date yourself. The only function is currentUser(), for assignee/reporter/creator. `archived` is this tracker's own field: archived issues are left out unless the query mentions it. `epic` is this tracker's own too, and it is the wide one: `epic = PM-12` matches that epic AND the work under it — its children and their sub-tasks — which is how one asks for an epic's whole board in a single clause. `parent` is the narrow one: direct children only, and never the epic itself. `agent` is this tracker's own as well: `agent = product` is an issue an agent of that role has right now — working on it or waiting on its question — and `agent IS NOT EMPTY` is any agent; the assignee of such an issue is still the person it works for. Quote values containing spaces. Seeded values — status: Backlog, "To Do", "In Progress", "In Review", Blocked, Done; statusCategory: "To Do", "In Progress", Done; priority: Highest, High, Medium, Low, Lowest; type: Epic, Story, Task, Bug, "Sub-task". A project's own columns (PM-170) can be searched too, by name — Segment = AI — or as customfield_20003 / cf[20003]; list_project_fields names them. | |
| text | No | Shorthand for `key ~ … OR summary ~ …`. Narrows the query further when `jql` is given too. | |
| limit | No | Max issues to return (default 25, max 100). | |
| status | No | Shorthand for `status = …` (e.g. 'In Progress', 'Done'). Narrows the query further when `jql` is given too. | |
| projectKey | No | Shorthand for `project = …` (must be visible to the token). Narrows the query further when `jql` is given too. |
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 that unknown fields are refused and named, that archived issues are excluded unless the query mentions archived, that archivedLeftOut indicates hidden matches, and that the default ordering is most-recent-first.
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?
Every sentence earns its place: purpose is front-loaded, then shorthand behavior, ordering, and the archived caveat. Dense but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex JQL search tool with no output schema, the description plus the exhaustive jql parameter schema covers evaluation, error behavior, filtering semantics, and result-count caveats. 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%, so per-parameter details are already thorough. The description adds valuable cross-cutting semantics: default ordering, archived-exclusion behavior, the refusal behavior for unknown fields, and the shorthand fallback.
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: 'Search the issues visible to this token, with a JQL query.' This clearly differentiates it from the sibling search_code and search_wiki tools and from get_issue.
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 when to use JQL versus shorthand filters, and explains how shorthand arguments combine with jql. It does not explicitly compare against sibling tools, but the usage context is otherwise unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search wiki pages visible to this token by free text (matched in the title, the body, and the labels written on an attached SVG diagram). Optionally restrict to one space key. Most recently updated first.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Free text to match in the page title, its body, or the text of an attached SVG diagram. | |
| limit | No | Max pages to return (default 25, max 100). | |
| spaceKey | No | Restrict to this space key (e.g. 'PM'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that only pages visible to the token are searched (auth context), that matching includes body and SVG labels, and that results are sorted most-recently-updated first. It doesn't mention return format or pagination beyond the limit parameter, but covers key behavioral traits 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?
Two concise sentences, front-loaded with the core purpose, followed by the optional restriction and sorting behavior. No wasted words, perfectly scannable for an agent.
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 search scope, optional space filter, and sorting, which is adequate for a search tool. However, with no output schema, it doesn't indicate what the result list contains (e.g., page IDs, titles, summaries) or whether pagination is handled beyond the limit parameter. This leaves a minor gap in expected return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter descriptions in the schema already explain text, limit, and spaceKey in detail. The tool description essentially repeats the same information, adding only the sorting note (which is not a parameter). Thus it adds no meaning beyond the schema, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'wiki pages', with specific scope: free text matched in title, body, and SVG labels, and optional space restriction. It distinguishes from siblings like get_wiki_page (retrieve specific) and list_wiki_spaces (list spaces) by emphasizing the free-text search behavior.
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 context on when to use: when you need to find pages by text, optionally within a space. It doesn't explicitly name alternatives, but the sibling list and the clear search purpose imply when this tool is appropriate. It omits explicit 'when not to use' but the free-text scope is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fill in a project's own columns on one issue, by their NAMES: 'Segment=AI; Country=Poland; Started=2026-08-01', or a JSON object. A country column takes the country's name or its two-letter code. An empty value clears the field, which is not the same as an empty one. A value that does not fit the field's kind — an option nobody offered, a date that is not one, a country that is neither — refuses the WHOLE call rather than writing part of it.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'CRM-1'. | |
| values | Yes | Field names to values, as 'Segment=AI; Country=Poland' or a JSON object. List values are given by option name, people by username, dates as 2026-08-21. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure, and it does so well: it explains empty-value clearing semantics, validation rules, and atomic failure behavior. It stops short of mentioning permissions, side effects, or whether unspecified fields are left untouched, so it is not fully transparent.
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 a concrete usage pattern and then adds necessary edge-case semantics in a compact, well-organized way. Every sentence carries information relevant to correct invocation, 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 two-parameter tool with fully documented parameters and no output schema, the description covers the main invocation details: syntax, value formats, clearing behavior, and failure modes. It is slightly incomplete because it does not state whether unspecified fields are preserved or reset, and gives no success-response expectations.
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 adds meaningful value beyond the schema by clarifying country-code alternatives, empty-value clearing semantics, and the all-or-nothing failure behavior, which helps an agent construct values 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 a specific verb ('Fill in') and a precise resource ('a project's own columns on one issue'), and distinguishes it from general issue updates by emphasizing custom project columns and field-name-based input. This clearly separates it from siblings like update_issue and set_project_field.
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 context: use this when setting project-specific columns on a single issue by field name. It does not explicitly name alternatives or state when not to use it, but the scope is specific enough that an agent can infer the intended use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a column to a project, or edit the one that already has this name. Keyed by name rather than by id: 'make sure there is a Segment field with these options' is the request, and a name is what you just read. A field's KIND cannot be changed once it exists. Project lead or admin only.
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | The glyph that mark wears, from the palette list_project_fields returns. Not for a country field: that one marks a card with the flag of the country the issue holds, so passing an icon is refused rather than ignored. | |
| kind | No | What it holds: 'text', 'number', 'date', 'user', 'select' (a list) or 'country' (a country, written as its name or its two-letter code and shown with a flag). Required when creating; ignored when the field already exists, since a kind cannot change. | |
| name | Yes | Field name, e.g. 'Segment'. An existing field with this name is edited rather than duplicated. | |
| newName | No | Rename the field to this. Leave out to keep the name. | |
| options | No | For a list: its options, as 'AI:green, Skins:orange, GameCards' or a JSON array of {name, color}. A colour is optional and must be one of: orange, amber, red, pink, purple, blue, teal, green. Options left out are REMOVED — send the whole set. | |
| showIcon | No | Mark a board card when this field has a value: true to switch the mark on, false off. Leave out to keep it as it is. | |
| projectKey | Yes | Project key, e.g. 'CRM'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and meets it: it discloses that a field's kind cannot be changed once it exists, that omitting options removes them, and that an icon is refused for country fields. These are non-obvious behaviors that the agent needs to know to avoid errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: the core purpose is front-loaded, followed by keying behavior, an example request, the kind immutability constraint, and access restriction. 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 7-parameter tool with no output schema, the description covers all critical behavioral nuances: creation vs. editing, name keying, kind immutability, options replacement, icon restriction, and access control. The schema handles parameter specifics, and the description fills the behavioral gaps completely.
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 significant context beyond the schema: it explains the name-keyed idempotency, the immutability of kind, the exact behavior for options (removal) and icon (refusal for country), which clarifies edge cases the schema alone doesn't convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Add a column to a project, or edit the one that already has this name.' It explicitly contrasts with sibling tools like delete_project_field and list_project_fields by describing the create-or-edit behavior, making the tool's role 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 states the access constraint 'Project lead or admin only' and explains the name-keyed behavior, which is a critical usage distinction. It doesn't explicitly name alternative tools, but the context (e.g., delete_project_field) is implied and the description is clear about when to use this tool for field creation/editing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make an existing project a subproject of another, or take it back out with an empty parentKey. This is about ACCESS, not about names or issues: everyone who may reach the parent may reach the subproject too, in the role they hold there. Nothing is renamed, no issue moves, and the keys stay ordinary keys. Attaching needs an admin or somebody who leads BOTH projects, since neither can be volunteered by whoever leads the other; detaching needs a lead of either, since it only takes access away. One level: a subproject cannot have subprojects.
| Name | Required | Description | Default |
|---|---|---|---|
| parentKey | No | Key of the project it becomes a subproject of, e.g. 'KYC'. Leave it out (or empty) to detach it and leave it a project of its own. | |
| projectKey | Yes | Key of the project to move, e.g. 'KYCB2B'. |
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 access propagation ('everyone who may reach the parent may reach the subproject too'), permission differences for attach vs detach, the one-level hierarchy constraint, and non-side-effects like no renaming or issue movement.
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, front-loaded with the main operation. Every sentence adds meaningful scope, permission, side-effect, or constraint information, with no fluff or redundant restatement of the schema.
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?
Covers permissions, access semantics, the one-level restriction, and non-effects. Combined with fully documented parameters, this gives an agent enough context to invoke the tool correctly even without an output schema or annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both 'projectKey' and 'parentKey' are already well described in the schema. The description reinforces the empty-parentKey detachment behavior, but it adds little parameter-level detail beyond what the schema already provides, 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?
States the specific operation: 'Make an existing project a subproject of another, or take it back out with an empty parentKey.' It also distinguishes its scope from sibling concerns by saying it is about 'ACCESS, not about names or issues' and explicitly that nothing is renamed and no issues move.
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 conditions for when to attach vs detach and clear role requirements: 'Attaching needs an admin or somebody who leads BOTH projects... detaching needs a lead of either.' The 'not about names or issues' clause gives useful when-not guidance, though it does not name sibling alternatives directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare a track on a project, or edit the one that already has this tag. The tag is the LABEL issues carry to join it ('cherry-orchard'), so it cannot contain a space — labels are stored space-separated. The name is what a reader sees ('The Cherry Orchard'); leave it out and the tag speaks for itself. Declaring a track writes nothing to any issue: the ones already carrying the label are in it at once. Needs permission to write in the project.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | The label that puts an issue in this track, e.g. 'cherry-orchard'. No spaces. An existing track with this tag is edited rather than duplicated; matched exactly, so 'Hamlet' and 'hamlet' are two tags, as they are two labels. | |
| icon | No | One or two emoji shown BESIDE the name, never instead of it. Leave it out to keep what is there; send an empty string to take it off. Anything that is not an emoji is refused rather than ignored. | |
| name | No | What a reader sees, e.g. 'The Cherry Orchard'. Leave it out to keep what is there; send an empty string to drop it and let the tag speak. | |
| newTag | No | Rename the tag to this. The label on existing issues is NOT rewritten, so work in the old tag leaves the track — rename only when the issues are being relabelled too. | |
| archived | No | true takes the track off the row above the board WITHOUT undeclaring it — a play that has been staged: its name, icon, place and tag are kept, its issues stay in it (they do not become 'outside every track'), and links to it keep working. false puts it back in the row. Leave it out to keep what is there. Prefer this to remove_track for a track that is finished. | |
| position | No | Where it sits in the row above the board, counting from 1. Leave it out and a new track goes last, an existing one stays where it is. | |
| projectKey | Yes | Project key, e.g. 'TH'. |
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 that declaring writes nothing to issues, that existing issues with the label are immediately in the track, that newTag does NOT rewrite labels on existing issues, that archived keeps issues in the track, and that non-emoji icons are refused. These are behavioral traits an agent cannot infer from the schema alone.
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-organized, front-loading the core action and tag/name distinction before diving into parameter details. Every sentence earns its place, though the length is substantial. It could arguably be tightened, but the density is justified given the tool's complexity and the absence of annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no annotations and no output schema, the description is remarkably complete. It covers the core semantics, the edit-vs-create behavior, the archived state, the newTag caveat, the icon validation, and the permission requirement. An agent has everything needed to call this 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%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains the tag/name distinction ('The tag is the LABEL issues carry to join it... The name is what a reader sees'), clarifies that leaving name out lets the tag speak, and explains the archived behavior in terms of 'a play that has been staged.' This elevates it above 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 states a specific verb ('Declare a track on a project, or edit the one that already has this tag') and clearly distinguishes the resource (a track identified by a tag). It differentiates from siblings like remove_track and list_tracks by explaining what declaring does and by explicitly preferring this tool over remove_track for finished tracks. The tag/name distinction is front-loaded 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?
The description explicitly says when to use this tool vs alternatives: 'Prefer this to remove_track for a track that is finished.' It also explains the semantics of editing vs creating based on tag existence, and clarifies that declaring writes nothing to issues. This is explicit routing guidance beyond what the schema provides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a link between two issues: name both ends (and, when more than one link joins them, the phrase — 'blocks', 'relates to'), or give the 'linkId' get_issue returned. Ambiguity is refused rather than guessed: two issues joined twice and no phrase given comes back with the links listed. Requires permission to edit BOTH issues. The issues themselves are untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | The other end, e.g. 'PM-417'. Not needed when 'linkId' is given. | |
| from | No | One end, e.g. 'PM-419'. Not needed when 'linkId' is given. | |
| type | No | Which link, when the two issues are joined by more than one: the phrase as get_issue says it ('blocks', 'is blocked by', 'relates to'). | |
| linkId | No | The link's id, as get_issue returns it in 'links'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it delivers: it discloses that only the link is removed ('The issues themselves are untouched'), that ambiguous cases are refused rather than guessed, and that editing both issues requires permission. This is strong behavioral disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the core action, packs in the alternative calling conventions, the ambiguity rule, permissions, and the no-side-effect guarantee, 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?
For a state-changing tool with no annotations and no output schema, the description covers the essential context: what is affected, what is not affected, permissions, and how ambiguity is handled. The only minor gap is that it does not describe the success return value, though it does mention the ambiguous-case response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents each parameter. The description adds value beyond that by explaining how the parameters interact: from+to/type is an alternative to linkId, and the ambiguity behavior ties directly to the type parameter. This goes beyond the 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 opens with the exact operation, 'Remove a link between two issues', with a specific verb and resource. It also distinguishes itself from the sibling link_issues by describing the inverse operation without needing to name it.
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 specifies two clear invocation strategies: name both ends plus the phrase when needed, or supply the linkId from get_issue. It also states a prerequisite ('Requires permission to edit BOTH issues'), but it does not explicitly contrast this tool with alternatives such as link_issues or update_issue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove the link between an issue and a wiki page. Identify the page by 'pageId', or by 'spaceKey' + 'title'. Requires permission to edit the issue. The page itself is not touched.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Exact page title, when identifying the page by title. | |
| pageId | No | Page id (as returned by search_wiki). | |
| issueKey | Yes | Issue key, e.g. 'UK-1'. | |
| spaceKey | No | Space key, when identifying the page by title. |
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 states the mutation (removes link), the prerequisite (requires permission to edit the issue), and a key side-effect boundary (does not touch the page). This adds meaningful behavioral context beyond the raw 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?
Three sentences with no wasted words. The action is front-loaded, then identification options, then permission and non-destructive behavior. Every sentence earns its place and contributes directly to correct invocation.
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 unlink operation with four parameters and no output schema, the description covers the core invocation details: purpose, identification methods, permission requirement, and the non-destructive outcome. It could mention error behavior when no matching link exists, but that is not essential for correct usage.
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 value by explaining the relationship between parameters: the page can be identified either by pageId alone or by spaceKey+title together. This alternative-grouping information is not explicit in the schema and helps an agent choose the correct 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 a specific verb and resource: 'Remove the link between an issue and a wiki page.' It clearly distinguishes this from sibling tools like link_wiki_page and delete_wiki_page, and the note 'The page itself is not touched' differentiates it from deletion. An agent can immediately understand the tool's function.
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 context for use: it removes a link, identifies the page via pageId or spaceKey+title, and requires issue edit permission. It does not explicitly name alternatives or state when not to use it, but the contrast with deleting the page is implied by 'The page itself is not touched.' This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a comment on an issue: pass 'body' to replace the whole of it, or 'edits' to change part of it — exact find-and-replace against the comment as get_comments hands it back, each 'oldText' occurring exactly once. One body axis per call. With 'edits' the answer says where each one landed rather than giving the comment back, so correcting one number in a long comment costs neither a resend nor a re-read. Nothing here takes a version and none is needed: an 'oldText' is matched against the comment as it stands now, so an edit whose text somebody has since rewritten is refused rather than applied over their words. The author may edit their own comment; anyone with full write access in the project may edit any. Answers with 'notified' — and note that this is only the people the edit newly reaches: names already present in the old text are not notified again, and the comment is not re-announced to watchers.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key the comment is on, e.g. 'UK-1'. | |
| body | No | The new body, replacing the old one entirely. Markdown is kept as written, and carries $…$ / $$…$$ LaTeX formulas and [~username] mentions. | |
| edits | No | Exact replacements in the comment, changing part of it in place. Matched against the body as get_comments returns it — stored as written, so what you read is what an 'oldText' has to equal, whitespace and line breaks included. Every edit is looked for in that text, not in what the edits before it produced; if any one does not fit, none is applied. | |
| commentId | Yes | The comment's id, as returned by get_comments or add_comment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and delivers: it explains matching against the comment as it currently stands, refusal of stale edits, atomicity ('if any one does not fit, none is applied'), permission rules, and exactly who gets notified. This goes far beyond the schema and gives the agent a precise side-effect model.
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 front-loaded, with every sentence earning its place: modes, matching rules, output behavior, permissions, and notifications. There is no filler and no redundancy with the input schema.
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, it covers both call shapes, how the response differs between 'body' and 'edits', notification behavior, permission requirements, and failure behavior. An agent can predict consequences before invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter interaction guidance: 'One body axis per call', exact text-matching semantics against get_comments output, and the explicit statement that no version parameter exists. It reinforces and clarifies the schema rather than just repeating 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?
Opens with a specific verb and resource ('Edit a comment on an issue') and immediately distinguishes the two operational modes: 'body' for full replacement and 'edits' for partial find-and-replace. This makes it clearly distinct from siblings like add_comment and update_wiki_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit internal usage guidance: use 'body' to replace the whole comment, 'edits' to change part, and explains when the edits mode avoids a resend or re-read. It does not explicitly name sibling alternatives such as add_comment or update_wiki_comment, so it stops just short of full when-not-to-use coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an issue: any of summary, description, type, assignee, priority, labels, dueDate, parentKey, or status (which performs the transition, and fires the project's rules — a rule may append a checklist to the description, in which case 'description' is listed in 'changed'). Only the fields you pass are changed. A project's workflow may put conditions on a move — that only certain people may make it, or that it must set certain fields — and a refusal names the condition and, where it is about who you are, lists the states you CAN reach. Fields a move requires must be sent in this same call, with 'resolution' and 'fields': a value set by an earlier call does not satisfy the condition. Answers with 'notified' (who this actually reaches) and 'unresolvedMentions' (what looked like a mention and reached nobody, each with a reason) — a wrong handle is stored as written and never refused, so that list is the only sign it did not land.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Issue key, e.g. 'UK-1'. | |
| type | No | New issue type name, e.g. 'Task', 'Bug', 'Story', 'Epic'. | |
| fields | No | The project's own columns to fill in with this update, by their NAMES: 'Segment=AI; Country=Poland', or a JSON object. Same shape as set_issue_fields — this exists here because a move a workflow conditions on a column has to set it in the same call. | |
| labels | No | Labels to set, space or comma separated. Replaces the existing set. | |
| status | No | Status name to move the issue to, e.g. 'In Progress', 'Done'. | |
| dueDate | No | The day this is due, as YYYY-MM-DD. A calendar day, not a timestamp. Pass an empty string to clear it. | |
| summary | No | New summary (title). | |
| assignee | No | Assignee username or email. Pass an empty string to unassign. 'agent:<role>' (e.g. 'agent:product') hands the issue to that agent instead: you become the assignee and the agent works on your behalf — allowed only where a switched-on duty of that role in this project takes issues like this one (list_project_rules shows the duties). | |
| priority | No | Priority name, e.g. 'High'. | |
| parentKey | No | Key of the issue this one hangs off, e.g. 'PM-276' — moves it under that story or epic. To DETACH it instead, send detachParent: true; an empty string still works but is easy to lose on the way. Nothing is renamed and the key never changes: an issue keeps the key of the project it lives in. A sub-task must stay in its parent's project; anything else may cross projects. | |
| resolution | No | Resolution name to set, e.g. 'Fixed', 'Won't Do'. Some workflows require one on the move into a finished state; sending it here is how that condition is met. | |
| description | No | New description. Markdown, with $…$ / $$…$$ LaTeX formulas and [~username] mentions. | |
| detachParent | No | Take this issue out from under its parent and leave it top-level. The reliable way to detach: unlike an empty parentKey it cannot arrive as the two characters "" or be dropped as «nothing was sent». Refused together with a parentKey, since the two would be asking for opposite things. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it is unusually transparent. It discloses that transitions fire project rules, rules can append checklists to the description, workflow conditions may refuse a move and name the condition, and required move fields must be included in the same call. It also explains response semantics for notified and unresolvedMentions, including that wrong handles are stored and never refused.
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 its core purpose and contains no fluff, but it is a dense single paragraph of long clauses and parentheticals that is harder to scan than a structured version would be. Breaking out workflow, detach, and mention-response behavior into clearer segments would improve parseability without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and annotations, the description supplies the response shape (notified, unresolvedMentions) and the non-obvious workflow-rule behavior an agent cannot infer from the input schema. The parentKey/detachParent nuances are left to the schema, but the schema documents them thoroughly, so 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 description coverage is 100%, so the schema carries the parameter-level detail. The description adds cross-parameter behavior beyond the schema: partial updates (only passed fields change) and the requirement that workflow-required fields be sent in the same call with resolution and fields. It does not redefine formats, but those are already documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an issue' and enumerates the updatable fields, including the special status-transition behavior, which clearly identifies the resource and operation. It does not explicitly contrast itself with sibling tools like move_issue or set_issue_fields, but the field list and transition caveat make its role distinct enough.
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 when-to-use context: only fields passed change, workflow moves can require fields in the same call, and status transitions fire project rules. It references set_issue_fields in the schema's fields parameter to explain why this call includes that parameter. It stops short of explicitly routing to move_issue or set_issue_fields, so usage guidance is contextual rather than a direct decision procedure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a project rule, by its id from list_project_rules. Only what you pass changes: pass just 'enabled' to switch a rule on or off, or any of the others to edit it. An empty string for 'type' or 'label' removes that condition; for a duty, an empty 'status', 'agentActions', 'agentFields' or 'doneStatus' clears that one. A rule's action cannot change. A rule appends its checklist to an issue's description when the issue ENTERS the rule's state — from the board, the Jira API or update_issue alike. The block starts with a hidden marker line '[//]: # (pm-rule:)'; while that line is in the description, entering the state again adds nothing (the journal says 'alreadyThere'). A [~username] in the template is a mention: that person is notified when the checklist lands. A checklist that would make the description too long is not added and the journal says 'tooLong'; the move itself still happens. A rule with action 'agent' is a DUTY instead: it says which issues may be handed to an agent role (agentRole, e.g. 'product') and what the agent may do with them. Its 'template' is then the INSTRUCTION — what doing such an issue means in this project — and nothing is appended anywhere. A duty may have no state (pass an empty 'status'): then an issue is handed only by a person. agentActions is a list from: describe, subtasks, ask, wiki, report, support. agentFields names the fields it may set: priority, labels, duedate, or the project's own fields by name. doneStatus is the state it moves the issue to when done — never a finished one. capUsd raises what one task may cost, up to 5 dollars. Commenting is always allowed; finishing, deleting, reassigning and anything outside the issue never are. Saving or switching on a duty makes it yours: it runs on your behalf and access, and is switched off if you lose the project. Project lead or admin only.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The rule's id, from list_project_rules. | |
| name | No | A new name. | |
| type | No | Only issues of this type, by name. An empty string means any type. | |
| label | No | Only issues with this label. An empty string means any label. | |
| capUsd | No | For a duty: what one task may cost, in dollars, at most 5; 0 goes back to the ordinary ceiling. | |
| status | No | A new state to fire on, by name. | |
| enabled | No | true to switch the rule on, false to switch it off. | |
| template | No | A new checklist template (Markdown). Replaces the old one for issues that enter the state from now on; checklists already added stay as they are. | |
| agentRole | No | For a duty: a new agent role key. | |
| doneStatus | No | For a duty: a new review state; an empty string and it no longer moves the issue. | |
| projectKey | Yes | Project key, e.g. 'ONB'. | |
| agentFields | No | For a duty: the whole new list of fields, comma-separated. | |
| agentActions | No | For a duty: the whole new list of actions, comma-separated. |
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 thoroughly: partial-update semantics, empty-string clearing, immutability of the rule action, checklist dedupe via hidden marker, mention notifications, too-long handling, duty specifics, ownership transfer, and project-lead/admin-only permission. This goes far beyond what annotations would typically disclose.
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 the tool is complex with 13 parameters and many edge cases. It is front-loaded with purpose and update semantics, then layers checklist behavior, duty specifics, and authorization. Every sentence covers a real behavioral nuance; none are 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 mutation tool with no annotations and no output schema, the description covers behavior, permissions, parameter relationships, and edge cases exceptionally well. It references journal messages ('alreadyThere', 'tooLong') but does not explicitly state the return/response shape or error behavior, which is a small gap given there is no 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?
Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantic value: it explains empty-string interactions across parameters, enumerates valid agentActions, constrains capUsd to 5 dollars, clarifies agentFields/doneStatus meanings, and explains that a duty's template is an instruction rather than a checklist. This is meaning the schema cannot express.
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 'Change a project rule, by its id from list_project_rules' – a specific verb, resource, and id source. This clearly distinguishes it from create/delete/list siblings and tells an agent exactly what the tool does and how to target an existing 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 clearly establishes this tool is for altering existing rules and explains partial-update behavior. Sibling names make the create/delete alternatives obvious, but the description does not explicitly say 'use create_project_rule for new rules' or 'use delete_project_rule to remove a rule'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a comment on a wiki page — your own, or anyone's with full write access in that project. Read it first with get_wiki_page(withMarkdown: true), which gives each comment its 'markdown' and 'version'. Pass 'markdown' to replace the whole comment, or 'edits' to change part of it (exact find-and-replace on that Markdown, each 'oldText' occurring exactly once) — the answer then says where each landed, not the comment. An inline comment's anchor moves with 'inlineSelection': the page text it should point at, copied exactly; an empty string turns it into an ordinary footer comment, which is the only way it ever stops being anchored. Mention someone as @Their Name, the wiki's own form. Answers with 'notified' — only the people the edit newly reaches, since names already in the old text are not notified again and the page is not re-announced to its watchers.
| Name | Required | Description | Default |
|---|---|---|---|
| edits | No | Exact replacements in the comment's Markdown — the text get_wiki_page returns as a comment's 'markdown'. Every 'oldText' is matched against it as you read it (not against the result of the other edits) and must occur exactly once unless 'replaceAll' is set; if any edit does not fit, none is applied. | |
| markdown | No | The whole comment, replacing what is there. Markdown, which also carries $…$ / $$…$$ LaTeX formulas. | |
| commentId | Yes | The comment's id, as get_wiki_page lists it or add_wiki_comment returned. | |
| inlineMatch | No | Which occurrence of 'inlineSelection' on the page to anchor to, counted from 1. Only needed when the text occurs more than once. | |
| expectedVersion | No | The version you read (from get_wiki_page). If the comment has moved on since, the edit is refused instead of overwriting somebody else's. | |
| inlineSelection | No | Move the inline anchor: the page text this comment should point at, copied exactly from the page. An empty string detaches it, making it a footer comment. Refused when the page does not carry that text, or carries it more than once and 'inlineMatch' does not say which — never resolved by guessing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It comprehensively explains side effects: version-check refusal, anchor detach semantics, notification behavior (only newly reached, not watchers), and the atomicity of 'edits'. These go well beyond the schema and cover all safety-relevant behaviors.
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?
Though lengthy, every sentence contributes necessary information. The structure is logical: purpose, prerequisite, editing modes, anchor behavior, mention format, and notification details. The description is front-loaded with the primary decision (whole vs. partial edit), and the complexity 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 6-parameter tool with no output schema, the description covers all relevant aspects: prerequisites, parameter usage, edge cases, and response expectations (where edits landed, 'notified' list). An agent has everything needed to call it correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema description coverage is 100%, the description adds meaning beyond it: it explains how 'edits' are matched against the read markdown (not other edits), the consequence of empty string for 'inlineSelection', and the meaning of 'expectedVersion' (refusal to prevent overwriting). It enriches each parameter's semantics with actionable 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 states a clear verb+resource ('Edit a comment on a wiki page') and specifies scope ('your own, or anyone's with full write access in that project'), distinguishing it from siblings like add_wiki_comment and update_comment. It also implies the read-before-edit flow that differentiates its usage.
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 preconditions ('Read it first with get_wiki_page(withMarkdown: true)'), two distinct editing modes (whole comment via 'markdown' vs. partial via 'edits'), constraints on 'edits' (exact match, uniqueness, replaceAll, atomicity), and behavior for anchoring and mentions. It clearly instructs when to use which parameter and what to do for each scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a wiki page: retitle it, change its body, move it under another parent (or to the top of its space), or set its labels. Identify it by 'id', or by 'spaceKey' + 'title'. To change part of the body, pass 'edits' (exact find-and-replace on the Markdown source, each 'oldText' occurring exactly once) or 'replaceSection' — the answer says where each landed, not the page, so a one-line fix to a long page costs one line. 'markdown' replaces the whole body — read it first with get_wiki_page(withMarkdown: true) and edit that, or the page's links, images and macros are dropped; 'appendMarkdown' adds to the end and leaves what is there untouched. Mention someone as @Their Name, the wiki's own form. Requires permission to edit the page. Answers with 'notified' (who this actually reaches) and 'unresolvedMentions' (what looked like a mention and reached nobody, each with a reason) — a wrong handle is stored as written and never refused, so that list is the only sign it did not land.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Page id (as returned by search_wiki). | |
| edits | No | Exact replacements in the page's Markdown source — the text get_wiki_page returns with 'section', 'offset' or withMarkdown: true. Every 'oldText' is matched against the page as you read it (not against the result of the other edits) and must occur exactly once unless 'replaceAll' is set; if any edit does not fit, none is applied. Pair with 'expectedVersion'. | |
| title | No | Current page title, when identifying the page by title. | |
| labels | No | Labels to set, space or comma separated. Replaces the existing set. | |
| message | No | Short note for the page history, e.g. why you changed it. | |
| markdown | No | The complete new body as Markdown — replaces what is there. Carries $…$ / $$…$$ LaTeX formulas and the wiki's macros on a line of their own ({toc}, {children}, {info} … {info}, {expand:title=…} … {expand}). | |
| newTitle | No | New title. The page's existing links follow the rename. | |
| parentId | No | Move the page under this parent page id. | |
| spaceKey | No | Space key, when identifying the page by title. | |
| minorEdit | No | Mark this as a minor edit in the history. | |
| toTopLevel | No | Move the page to the top of its space, out from under any parent, so it sits beside the space's other root pages. Use this instead of parentId/parentTitle — a tool argument has no way to say 'no parent' by leaving one out. | |
| parentTitle | No | Move the page under the page with this title, in the same space. | |
| appendMarkdown | No | Markdown to add to the end of the page, leaving the rest as it is. Same syntax as 'markdown'. | |
| replaceSection | No | Replace one whole section: 'section' names it as get_wiki_page's 'section' does (anchor or heading text), 'markdown' is what replaces it — heading line included, as reading the section returned it. Can be combined with 'edits' elsewhere on the page. | |
| expectedVersion | No | The version you read (from get_wiki_page). If the page has moved on since, the edit is refused instead of overwriting someone else's. |
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 discloses destructive behavior ('markdown' drops links, images, and macros unless read first), atomicity (no edit applies if any doesn't fit), version-check refusal, and the mention resolution behavior (unresolvedMentions list, wrong handles stored as written). This goes well 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 a single dense paragraph but each clause earns its place, covering purpose, identification, all edit modes, warnings, and output behavior. It is front-loaded with the main purpose and uses commas and semicolons to keep related ideas together. Slightly long, but efficient given the tool's complexity.
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 15-parameter tool with no output schema and no annotations, the description is exceptionally complete. It covers identification, all edit strategies, permission, the return fields (notified, unresolvedMentions), and the destructive risk of 'markdown'. Nothing an agent needs to call it correctly appears 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 input schema has 100% coverage with detailed descriptions for every parameter, so the baseline is 3. The description adds strategic context beyond the schema, such as the trade-off between 'edits' and 'replaceSection', the note that the answer reports where edits landed, and the mention syntax. It enriches but doesn't repeat the schema, meriting 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 opens with a precise verb and resource ('Edit a wiki page') and enumerates the exact operations: retitle, change body, move under parent, set labels. It clearly distinguishes from siblings like create_wiki_page and update_wiki_comment by stating what it does not do (e.g., it edits existing pages, not 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?
The description gives explicit guidance on parameter selection: 'edits' for exact find-and-replace, 'replaceSection' for whole sections, 'markdown' to replace the whole body (with a warning to read first), and 'appendMarkdown' to add without touching existing content. It also explains identification by id or spaceKey+title, and notes the permission requirement, making it clear when to use this tool and how to avoid pitfalls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Admin only: create or update a project's external MCP connection. Pass 'id' to update an existing one (omit to create). 'token' is stored server-side and never returned; omit it to keep the current token when updating.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Existing connection id to update; omit to create a new one. | |
| url | No | MCP server URL — use https (required when creating). | |
| name | No | Connection display name (required when creating). | |
| token | No | Bearer auth token. Omit to keep the current token when updating. | |
| enabled | No | Whether the connection is enabled. | |
| projectKey | Yes | Project key, e.g. 'UK'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that the tool is admin-only, that tokens are stored server-side and never returned, and that omitting token preserves the current value when updating. These are meaningful side-effect and security details 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?
Two crisp sentences with the most important scoping information first: admin-only, create/update behavior, then the id/token nuances. Every clause earns its place with 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 tool with no annotations and no output schema, the description covers the critical behavioral contract: creation vs update, admin restriction, and token handling. It could mention that url and name are needed when creating, but the schema already documents those requirements, so the definition is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the upsert semantics ('pass id to update, omit to create') and the non-return of tokens, which complements the schema's parameter descriptions. It doesn't add much for url/name/enabled/projectKey, but those are already well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: create or update a project's external MCP connection. It also clarifies the create-vs-update distinction up front, which differentiates it from read-only siblings like list_mcp_connections.
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 direct operational guidance: pass 'id' to update, omit it to create, and omit 'token' to retain the current token. It also notes the admin-only restriction. It stops short of naming alternatives, but the usage conditions are explicit and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Take back a question you asked, when it no longer needs answering — you worked it out, or the task moved on. The comment stays in the thread (the conversation happened) and the question stops counting on the other person's list. The person who asked, or anybody with full write access in the project.
| Name | Required | Description | Default |
|---|---|---|---|
| questionId | Yes | The question's id, as returned by list_issue_questions or ask_issue_question. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses key side effects: the comment stays in the thread while the question is removed from the other person's list, and it states permission requirements. It does not mention edge cases like whether the question must be unanswered or what happens if already withdrawn, but the core behavior is transparent.
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 that lead with the purpose, then cover behavioral effects and permissions. Every sentence adds value without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers purpose, usage triggers, side effects, and permissions. Minor gaps include unspecified error/edge-case behavior (e.g., withdrawing an already-answered or already-withdrawn question), but these are not critical for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter (questionId) is fully described in the schema ('as returned by list_issue_questions or ask_issue_question'), and the description adds no extra meaning beyond that. With 100% schema coverage, the baseline of 3 applies; no additional parameter guidance is necessary.
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 ('Take back a question you asked'), the resource (a question), and the condition under which it applies (when it no longer needs answering). It differentiates from sibling tools like ask_issue_question and answer_issue_question by focusing on retracting a question rather than posing or answering one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use conditions ('when it no longer needs answering — you worked it out, or the task moved on') and clarifies who may use it (the asker or anyone with full write access). It doesn't explicitly contrast with answer_issue_question (e.g., 'if you solved it, consider answering instead'), but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_attachmentadd_commentadd_wiki_attachmentadd_wiki_commentadmin_bank_transferadmin_errors_weekadmin_funneladmin_invoicesadmin_landing_weekadmin_loadadmin_overviewadmin_set_bank_transferadmin_workspace_journaladmin_workspacesanswer_issue_questionask_issue_questioncreate_issuecreate_projectcreate_project_rulecreate_wiki_pagedecide_support_letterdelete_agent_usagedelete_attachmentdelete_project_fielddelete_project_ruledelete_wiki_attachmentdelete_wiki_pageget_agent_usageget_attachmentget_changeget_commentsget_issueget_project_rule_runsget_support_letterget_support_requestget_wiki_attachmentget_wiki_pagelink_issueslink_wiki_pagelist_codelist_credentialslist_issue_questionslist_mcp_connectionslist_project_fieldslist_project_ruleslist_projectslist_support_letterslist_support_queuelist_trackslist_userslist_wiki_spacesmove_issueread_coderemove_trackreply_to_requesterreport_agent_usagereveal_credentialsearch_codesearch_issuessearch_wikiset_issue_fieldsset_project_fieldset_project_parentset_trackunlink_issuesunlink_wiki_pageupdate_commentupdate_issueupdate_project_ruleupdate_wiki_commentupdate_wiki_pageupsert_mcp_connectionwithdraw_issue_questionNifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Shared memory for coding agents and their teams: project docs with semantic search, plus epics, tasks, open questions and decisions your agent reads and writes over MCP. Teammates and their agents share the same board. Deploy and permanent delete stay human-only and are enforced by the server. Free tier, no card. Setup: https://app.bilgai.com/docs/connect — API key (blg_) as Bearer or OAuth. Issues: https://github.com/volkansuner/bilg-feedback
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
Add one secure layer between your agents and this server.
