Kaiku

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

Annotations already flag destructiveHint=true; the description earns credit for making that concrete — attaching an existing filename replaces that file rather than duplicating, so retries cannot double it. It also discloses the required permission (edit issues in the project) and that it returns a download URL. Only size limits or failure modes are 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?

Four sentences, core action front-loaded, then the replacement/idempotency guarantee, then the alternative path, then return value and permission. No sentence restates the schema or the annotations verbatim.

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 5-param mutation tool with no output schema, it covers what an agent needs: content encoding choice, replacement semantics, the preferred alternative for local files, the returned URL, and the permission gate.

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 param is well documented, so the baseline is 3. The description adds real value on top by framing text vs contentBase64 as a decision with a mutual-exclusion rule and by pointing at an external server for the local-path case.

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 plus scope ('Attach a file to an issue'), and immediately enumerates the two content modes. The scope word 'issue' distinguishes it from the sibling add_wiki_attachment 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?

Gives explicit when-to-use-which guidance: 'contentBase64' for bytes, 'text' when the file is text, and routes local-disk files (screenshots, PDFs) to the pm-files MCP server via local_files_setup rather than base64. It also tells the agent that retrying is safe, which is a usage condition in itself.

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

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

Goes well beyond annotations (which only say non-read-only, non-destructive, closed-world): discloses notification fan-out rules (answered author told once even if mentioned), authorization requirements, that wrong handles are silently stored, and the agent-invocation protocol with its failure reasons. This is rich behavioral context an agent cannot get from structured fields.

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

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

Front-loads the core action, but the remainder is a single dense paragraph with very long sentences mixing reply semantics, return fields, and agent behavior. Information is mostly earned, but the packing hurts scannability.

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

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

With no output schema and only basic annotations, the description anticipates the return payload ('notified', 'answered', 'unresolvedMentions', 'agents') and failure modes, and covers permissions and mention pitfalls. An agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100% and the schema already documents key, body (Markdown/LaTeX/[~username] via list_users) and replyTo (same issue, not deleted). The description restates much of that and adds only marginal detail (the [~agent:role] syntax), 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?

States a specific verb (add) and resource (comment on an issue), plus the reply variant, and implicitly distinguishes itself from update_comment/get_comments by naming get_comments as the id source. An agent can tell this creates a comment rather than editing 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?

Gives clear conditions: use 'replyTo' with a comment id from get_comments to answer a specific comment, and states the permission prerequisite (read-only members cannot comment). It does not explicitly contrast with update_comment or add_wiki_comment, so it falls short of naming alternatives/exclusions.

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

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

Goes well beyond the annotations (readOnly false, destructive false): it discloses idempotency ('same place of same act already there → added false'), asynchronous act fetching ('hasText may be false at first'), and required permissions. These are exactly the traits an agent needs to avoid misinterpreting a success.

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 opening verb+resource is front-loaded, but the body is a dense run of parenthetical clauses and abrupt fragments ('it is yours, accepted at once') that hurt scannability. Several sentences could be tightened 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?

For a 5-parameter mutation with no output schema, the description covers targets (issue/page/comment), permissions, background-processing side effects, and the idempotent result signal. Nothing essential for a correct call 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 schema coverage is 100%, the description still adds meaning: url must point to an official source site, place is stated in words ('Article 18'), and commentId anchors the reference inside a comment rather than the issue/page body. This enriches rather than repeats 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 ('Put a reference to a legal act on an issue or a wiki page') and scopes the target objects, which clearly separates it from siblings like add_attachment or add_comment. The analogy to the UI 'Add' in the 'Legal acts' block makes the operation 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?

Explains the conditions for use: it requires a project that keeps legal references and permission to edit the issue/page (or comment). It clarifies the commentId alternative, but never names sibling tools such as list_legal_references or remove_legal_reference to route the agent explicitly.

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

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

With annotations only declaring a non-readonly, non-destructive, non-open-world write, the description carries substantial extra context: the audience becomes the whole internet (even anonymous readers), later edits propagate, the rest of the source project stays closed, links to closed items are counted but never named, and claim status mirrors the register. It also discloses side effects (both projects' journals) and the irreversibility implied by publication.

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

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

Purpose and irreversibility framing are front-loaded and every clause carries information (permissions, propagation, journaling, confirmation). The prose is dense and clause-chained, which costs some readability, but it is 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 5-parameter mutation tool with no output schema, the description covers the permission model, mutex on selector parameters, propagation semantics, audit journaling, and the human-confirmation warning — everything an agent needs before calling it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuine constraint absent from the schema: exactly one of issueKey, pageId or claimId must be supplied. It also clarifies that edition is page-only and that re-calling switches the shown editions, adding meaning beyond the field docs.

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

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

States a precise verb and resource set ('Show one issue, one wiki page or one claim of a PRIVATE project in a public project') and immediately scopes it as 'by reference, not as a copy', which separates it from copy/create siblings and from list_showcase/remove_from_showcase.

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 strong when-conditions and prerequisites: exactly one of issueKey/pageId/claimId, only the owning project's owner who also administers the public project, and the target must be public. It also says to confirm with the person first. It does not name the sibling for undoing this (remove_from_showcase) or for reviewing what is already shown (list_showcase), so 4 rather than 5.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false; the description earns its keep by explaining exactly what that destruction means — re-attaching the same filename replaces the bytes and bumps the version, so retries are idempotent and cannot produce duplicate copies. It also discloses the permission requirement to edit the page and the dark-theme variant naming convention, none of which appear in the annotations.

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

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

Information-dense and front-loaded: identifying scheme, content modes, then idempotency, then routing advice, then the follow-up step. It is longer than most descriptions, but nearly every sentence carries a constraint the agent could not infer, so only minor tightening is possible.

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 mutation tool with no output schema, the description covers the addressing semantics, the return value ('the answer hands you the Markdown'), the permission prerequisite, and the follow-up call required to make the attachment appear in the page body. Nothing an agent needs in order 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 coverage is already 100%, so the baseline is 3. The description still adds meaning the schema doesn't: the valid page-identification combinations, the 'contentBase64' vs 'text' exclusivity, and the '-dark' before-extension convention for dark-theme image variants. That extra is modest because the schema already documents each parameter individually.

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

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

States a specific verb+resource (attach a file to a wiki page) and immediately gives the two addressing modes ('pageId' or 'spaceKey' + 'title') and the two content modes (bytes vs 'text'). This is clearly distinguishable from the sibling add_attachment (non-wiki) and from delete_wiki_attachment/get_wiki_attachment.

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

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

Explicitly routes the agent: use the pm-files MCP server by path instead for local files like screenshots or PDFs (pointing to local_files_setup), and use 'text' rather than base64 for text files. It also names the follow-up step, telling the agent the attachment is not visible on the page until update_wiki_page adds the returned Markdown reference.

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

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

With annotations only indicating non-read-only and non-destructive behavior, the description adds the notification side effect (author notified once even if also mentioned), the permission requirement, Markdown/mention rendering rules, and the fact that a wrong handle is stored as written and never refused. This is substantial behavioral context beyond the annotations.

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

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

It front-loads the action and packs notification, mention, permission, and return-value details without filler. However, it is a dense semicolon-heavy paragraph, so structure could be easier to scan.

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

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

No output schema exists, and the description fully explains the return fields 'notified', 'answered', and 'unresolvedMentions', including why 'unresolvedMentions' matters. Given the mutation complexity and auth requirements, it covers what an agent needs to call and interpret 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?

Schema coverage is 100%, so baseline is 3; the description adds that 'replyTo' is a comment id from 'get_wiki_page', that the page can be identified by 'pageId' or 'spaceKey' + 'title', and that the body supports rendered Markdown plus the wiki mention form. It does not document every parameter's full constraints, but it adds useful 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 first clause gives a specific verb and resource ('Comment on a wiki page') and immediately distinguishes the reply mode via 'replyTo'. It also names where 'replyTo' comes from ('get_wiki_page'), so an agent can tell this apart from a generic comment tool.

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

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

It states the two use cases (new comment vs. reply), how to identify the page ('pageId', or 'spaceKey' + 'title'), and the prerequisite permission to comment. It does not explicitly route agents to 'update_wiki_comment' or 'add_comment' for other comment operations, so it is clear but not fully alternative-aware.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real context on top: an admin-only authorization requirement, the exact semantics of the 'offered' flag versus 'enabled', and the fact that already-issued bills carry a frozen copy unaffected by this response. It stops short of describing response shape or ordering.

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

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

Front-loaded with the admin gate and the resource, and every subsequent clause carries substantive domain meaning — the 'offered'/'enabled' distinction and the frozen-bill immutability note both earn their place. The first sentence is a long run-on list, which costs some readability.

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 parameters and no output schema, the description carries the return-value burden and does so well: it enumerates the returned fields, explains the derived 'offered' flag, and states the currency behavior. The only gap is the missing hand-off to the mutating counterpart.

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

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

Zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description productively spends its space on the meaning of returned fields instead, notably clarifying 'offered' vs 'enabled' and the USD normalization.

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 makes clear this surfaces the current bank-transfer destination configuration, and it enumerates the specific fields involved (beneficiary, account, bank/SWIFT, intermediary, purpose line, wire days, last editor). It never names the obvious sibling, admin_set_bank_transfer, so the read-vs-write distinction has to be inferred from the annotations and the phrase 'is not changed by what this returns'.

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

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

'Administrators only' gives an access precondition, and the content implies this is a read of live settings. But there is no explicit when-to-use statement and no routing to the alternative — an agent wanting to modify these values gets no pointer to admin_set_bank_transfer.

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

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

Annotations only cover read-only/non-destructive/open-world, but the description adds real behavioral context the agent can't get elsewhere: admin gating, the null-counts-plus-reason semantics for unanswered projects ("never zeros", a genuine misinterpretation trap), and that the numbers match the weekly error 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?

Front-loaded access constraint, then contents, then the null-vs-zero caveat, then the parameter hint — a sensible order with little waste. The middle enumeration is dense and slightly list-like in prose, but each item signals report scope the agent needs to judge relevance.

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

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

No output schema exists, so the description compensates by enumerating the report's sections and explicitly documenting the null/reason representation instead of raw values. For a single-parameter read tool, nothing needed to call it or interpret results 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?

With one parameter at 100% schema coverage, the schema already defines weeksAgo's 0/1 semantics. The description's "Ask for an earlier week with weeksAgo" confirms intent but adds no format, range bounds, or behavior for larger values, so baseline 3 applies.

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

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

A specific verb-and-resource-by-scope statement: the error collector's week, itemized into events/distinct errors per project, week-over-week, first-seen, loudest, and regressed errors. An agent can tell immediately this is the weekly error digest rather than the funnel/landing-week or general overview 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?

"Administrators only" is an explicit access prerequisite, and "Ask for an earlier week with weeksAgo" tells the agent how to reach historical weeks. It stops short of naming alternatives or when-not-to-use (e.g., vs admin_overview or admin_funnel), so no explicit exclusions.

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

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

Well beyond what readOnlyHint/openWorldHint/destructiveHint declare: it explains data provenance ('the fleet's ledger'), that stale machines make totals older rather than wrong, and that null means 'not reported' rather than zero ('never zero', 'ai.missing' names it). The only shortfall is that churn and purchases are named in the opening but never explained behaviorally.

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

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

A single unstructured block of roughly 450 words covering seven distinct output sections, with no bullets, headers, or paragraph breaks; the reader must parse a data dictionary to find the purpose. Most content is substantive, but the null-vs-zero rule is restated three separate times ('never zero' three times), and the length is not front-loaded beyond the first clause.

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

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

No output schema exists, so the description must carry the entire return structure — and it does, walking through activation, legal, ai, firstSession and segments, including the segment-overlap and cohort caveats. Minor gaps remain (churn, purchases/conversion definitions), but an agent can consume the response without further documentation.

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 three parameters (from/to/days) are fully documented there, including the 90-day default and 730 cap. The description adds only 'Default period: the last 90 days', which is essentially already in the schema, so baseline 3 applies.

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

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

Opens with a concrete scope statement — 'the installation as a business over a period — registrations, ... purchases and conversion by cohort, churn, and money' — plus an access constraint ('Administrators only'). That is specific enough to separate it from a generic overview, but it never names a sibling (admin_overview, admin_landing_week, site_traffic) to say which reporting tool to pick.

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?

'Administrators only' and 'Default period: the last 90 days' give a caller constraint and a default, which is useful. But there is no statement of when to reach for this versus admin_overview or admin_landing_week, and no exclusion guidance; the when-to-use is only implied by the metric list.

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false), and the description goes further: amounts are never aggregated across coins, rows stay in their own currency, and a machine's delivery record for an invoice is not rolled up, with the response explicitly signalling absence instead of returning an empty list. These are non-obvious output caveats that an agent could not derive from the annotations or 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 access restriction and the row contents are front-loaded in the first clause, and each subsequent sentence carries distinct behavioral information rather than restating the name. Some phrasing is oblique ('what answered it', 'the fleet's ledger'), which costs a little clarity but not much 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?

With no output schema, the description must carry return-value meaning, and it does: per-row fields, the no-cross-currency rule, machine freshness, and the missing-delivery-record behavior. Pagination and bounds are left to the schema's limit parameter, which is acceptable. Terms like 'machines' and 'fleet's ledger' are used without definition, so an agent must infer the domain.

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 slug, limit, and status are already documented with defaults and bounds. The description adds nothing about filtering, ordering, or how status values combine with the company filter, so baseline 3 applies.

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

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

The description names a concrete resource (invoices) and enumerates what each row carries: amount, coin, paid status, shortfall, and payments against it. It does not differentiate itself from nearby admin_ tools (admin_workspaces, admin_bank_transfer, admin_overview), but the object read is otherwise 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 only explicit constraint is 'Administrators only', which states the audience but not the call conditions. There is no guidance on when to prefer this over the other admin_ reporting tools, nor when not to use it. Usage is implied by the resource rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful context beyond annotations: it requires administrator privileges, clarifies that only figures (not the rendered message) are returned, and notes that the numbers match the weekly monitoring 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 three tightly written sentences: purpose and metrics first, then context about the weekly report, then parameter usage and an output caveat. No sentence is wasted, and the most important 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 simple read-only analytics tool with one optional parameter and no output schema, the description covers purpose, access restriction, parameter usage, and an output limitation. It could say more about the shape of the returned figures, but annotations and schema already provide most of what an agent needs 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 the parameter is fully documented in the schema. The description's mention of 'Ask for an earlier week with weeksAgo' adds little beyond the schema's own description ('0 is the last full week, 1 the one before it'), 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 states a specific resource (the landing site's week) and lists the exact metrics returned: visits, sources, sign-up clicks, and registrations. It does not explicitly differentiate from siblings like admin_funnel or site_traffic, but the specificity is enough to distinguish it in practice.

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 only usage constraints given are 'Administrators only' and a note on using weeksAgo for earlier weeks. There is no guidance on when to choose this tool over alternatives such as admin_overview, admin_funnel, or site_traffic, leaving the agent to infer selection.

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

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

Annotations already declare the operation read-only, non-destructive, and closed-world, so the safety profile is covered. The description adds substantial operational context beyond that: load is machine-local, each metric is used-vs-allowed where an allowance exists, spend is estimated from recorded prices, and requester identity is excluded.

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 dense sentences and front-loads the admin-only condition and core purpose. It is efficient and every sentence carries relevant scope or caveat information, though the load-component list makes it slightly heavy.

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 metrics tool with one optional parameter and no output schema, the description explains what is measured, how model costs are estimated, and what is deliberately excluded. That gives an agent enough context to invoke it and interpret the response at a high level.

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 `days` parameter is fully documented in the schema, including the default of 30 and the special value 0 for all time. The description only mentions a rolling window and does not add format or boundary details beyond the schema, so the baseline 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 opens with an administrators-only qualifier and states the two resources it covers: this machine's load and language-model cost. It names the load dimensions and spend breakdowns, making the scope distinct from generic admin metrics, though it does not explicitly name a sibling alternative such as admin_overview or site_traffic.

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 establishes a clear usage condition ('Administrators only') and the context in which the tool applies: machine-local load and model spend. It also includes an exclusion ('Who spent it is not returned here'), but does not point to a specific sibling for per-user spend, leaving that routing implicit.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, closed-world); the description adds real behavioral context the annotations cannot: totals are null rather than zero when a fleet machine is unreachable, the 'fleet' field reports which machines answered, and the breakdowns are scoped to the local machine. It even tells the agent how to interpret a null — a genuine semantic trap avoided.

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

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

Front-loaded with the audience and scope, then the fleet/null caveat, which is the most decision-relevant detail. Slightly longer than needed: the null-as-'nobody knows' point is made twice ('A total is null, never zero' and 'Read a null as nobody knows, never as none'), costing a sentence without new information.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does: enumerates the counted entities, the two breakdowns, and the fleet/here companion fields. An agent knows both what it gets and how to read the missing-data cases before calling.

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

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

There are zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It spends none of its text on non-existent inputs, which is correct.

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 concrete resource (the whole installation's counts: accounts, workspaces, projects, issues, comments, sprints) plus breakdowns, and makes the scope distinction explicit — 'the installation's rather than one company's' — which separates it from workspace-scoped siblings like admin_workspaces. An agent can identify what it returns without opening any schema.

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

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

'Administrators only' states the prerequisite, and the installation-vs-company framing tells the agent when this aggregation is the right one. It stops short of naming a specific alternative (e.g. admin_workspaces, site_traffic) or stating when not to use it, so the routing is implied rather than spelled out.

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

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

Annotations already mark this as non-readonly and destructive, but the description adds substantial behavioral context: omitted fields are cleared, enabling can be refused for missing required fields, the change is attributed to the calling administrator, and issued bills retain old details. However, its blanket statement that anything left out is cleared conflicts with the schema note that daysToArrive is kept when omitted.

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 critical admin-only destructive whole-set behavior and then moves through refusal rules, minimumUsd semantics, audit trail, and issued bills. It is longer and more repetitive than necessary, but the length is mostly justified by the destructive 13-parameter operation.

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 13-parameter mutation with no output schema, it covers the important prerequisites, refusal behavior, whole-set replacement risk, audit attribution, and effect on already-issued bills. It still lacks clarity around exceptions such as daysToArrive retention and purpose defaulting, which are important 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?

Schema description coverage is 100%, so the baseline is 3. The description adds some useful semantics, especially that minimumUsd is a floor on the method rather than the debt and that purpose must carry {invoice}. But the blanket 'anything left out is cleared' claim conflicts with schema details such as daysToArrive being retained when omitted, reducing the value of that added 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 admin-only mutation: setting where bank transfers are sent. It clearly distinguishes this write operation from the read sibling admin_bank_transfer by telling the agent to read that first. An agent can identify the resource and action without opening the schema.

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

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

It gives explicit usage conditions: administrators only, read admin_bank_transfer first, and repeat unchanged values because the whole set is sent every time. It also states when enabling is refused and that disabling is never refused, which directly guides invocation.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true; the description adds the auth requirement (administrators only), the downstream semantic effect on the funnel, and the override rules for unbilled/demo companies. It also describes the response shape ('ours' and 'oursBy' with values marked/not-billed/demo). It does not explicitly reconcile the destructive hint with what is effectively a reversible flag toggle, so a 4 rather than a 5.

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

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

The critical constraints (admin-only, mutating) are front-loaded in the first clause, and every sentence carries information. There is some conversational padding ('our own, a test somebody here made') and the funnel explanation is slightly verbose, but nothing is 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?

With only two parameters, full schema coverage, and no output schema, the description covers everything an agent needs: auth gate, mutation nature, semantic effect, edge cases (unbilled/demo), and the returned fields. Nothing material is missing.

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

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

Schema coverage is 100% and both parameters already carry descriptions (including the true/false meaning of 'ours' and the slug's source). The description adds conceptual meaning about what the mark does but no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: mark a company as 'one of ours' or remove the mark, and explicitly says this CHANGES things. It is distinguishable from admin_workspaces (which merely lists companies) and from the funnel tools, since it explains the mark's effect on the funnel's 'firstSession'.

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 operating context: administrators only, used to classify a company as internal/test versus external for funnel purposes. It also notes the override rule that non-billed or demo companies are 'ours' regardless of the mark, which tells the agent when the flag is even meaningful. It stops short of naming an explicit alternative tool or when-not-to-use condition.

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

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

Beyond readOnlyHint, it discloses administrator-only access, newest-first ordering, a 100-entry cap, reason capture, actor identity, and remote-machine behavior. These are context an agent needs to interpret results and scope, not safety claims already covered by annotations.

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

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

Front-loads scope and key constraints, and every sentence is relevant to interpretation. Some narrative flourishes ('because an entry without one answers nothing') make it longer than necessary for a one-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?

With no output schema, the description still explains return content, ordering, entry limit, actor/reason inclusion, and the remote-machine fallback. It also sets administrator scope, so an agent has enough to call and interpret the result.

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

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

The only parameter, slug, has a rich schema description (100% coverage), so the schema carries the parameter meaning. The description only says 'one company' without adding slug syntax or validation, making baseline 3 appropriate.

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

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

States a specific resource and scope: an administrator audit journal of actions taken on one company, including action types, actor, and reason, newest first. This distinguishes it from aggregate siblings like admin_workspaces and admin_overview by being per-company and historical.

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 a concrete use case ('why is this company on a period nobody paid for') and an administrator-only precondition, plus a boundary for companies hosted on another machine. It does not explicitly name an alternative tool or when to prefer it over admin_workspaces, so it falls short of a 5.

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

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

With readOnlyHint/destructiveHint already covering the safety profile, the description still adds real behavioral context: a null meter reading means the machine was not asked rather than idle, owners are excluded by default, and an e-mail address is never returned. Those are exactly the traps an agent would otherwise misreport.

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

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

Front-loaded with the audience and scope, then filters, then caveats; every sentence carries information. It is a dense single block without list structure, which slightly slows scanning of the four distinct filter behaviors.

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

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

For a read-only list tool with no output schema, the description covers what is returned (plan, state, expiry days, usage vs quota, balance), how to narrow it, and the null/omission edge cases. An agent has enough to call it and to interpret the output correctly without further probing.

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 semantics beyond the schema: endingInDays is framed as the trial-expiry answer, withOwners is framed as a deliberate privacy default, and the null-meter caveat affects interpretation of results. The only flaw is the undocumented 'attention' value that appears in prose but not in the status enum.

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 resource and scope: 'every company on the installation' with plan, state, expiry, usage against quota, and balance. An agent immediately knows this is a read-only tenant roster. It does not explicitly differentiate itself from nearby siblings like admin_overview, admin_load, or admin_invoices, but the enumerated payload makes the intent 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?

Concrete guidance is given for endingInDays — it explains that this is how 'whose trial ends this week' is answered in one call — and it mentions the 'attention' shortcut for rows needing review. No exclusions or named alternative tools are offered, and the 'attention' value is not present in the status enum described in the schema, which leaves a small gap for an agent to resolve.

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

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

Goes well beyond the annotations: it discloses the authorization rule (addressee only), the replace-on-repeat-answer semantics, the deadline-passed override and its recording, and the side effects (answer posted as an ordinary comment, asker notified). These are exactly the mutation consequences an agent needs and that destructiveHint=false does not convey.

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, front-loaded with the core action and eligibility, then consequences. No filler and every sentence carries distinct information (eligibility, re-answer, deadline, side effects).

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

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

For a 3-parameter mutation with no output schema, the description covers action, authorization, idempotent-replace behavior, edge cases and visible side effects, with discovery of the question id covered by the schema. 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 description coverage is 100%, so questionId, option and note are already fully documented, including the 0-based option index and the free-text caveat. The description adds only the notion of choosing 'one of its options' and does not extend the parameters' meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Answer a question ... on an issue, by choosing one of its options'), which is unambiguous next to ask_issue_question, list_issue_questions and withdraw_issue_question. However, it never names those siblings explicitly, so the differentiation is inferred from wording rather than 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?

Gives concrete eligibility ('Only the person the question was addressed to may answer it') plus edge-case guidance for re-answering and for questions whose deadline passed. It stops short of routing the agent to alternatives (e.g. use list_issue_questions to discover ids, withdraw_issue_question to cancel), so it is clear context rather than a full when/when-not map.

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

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

Beyond the annotations, the description discloses important behavior: an author's answer is reported to the reviewer, 'fixed: false' leaves the remark standing and causes the next edit to ask again, and 'reopen'/'withdraw' are reviewer-only actions. These details clarify permissions and state transitions that the annotations alone do not provide.

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: it states the purpose first, then explains author versus reviewer semantics in a dense but purposeful way. Every clause adds operational meaning, with no redundant restatement of the title or 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, the description covers the necessary context: who may call it, what each response mode does, and how the reviewer is notified. No critical behavioral information appears to be missing 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?

Schema coverage is 100%, so the schema already defines the parameters, but the description adds meaningful semantics for the role-specific use of 'fixed', 'action', and 'note'. It clarifies that 'fixed: false' is compared against the current version and that reopening/withdrawing are reviewer actions, though it does not further elaborate on 'remarkId'.

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: 'Answer a remark of a page's review.' It also points to the sibling tool get_wiki_page_reviews, making the distinction between finding remarks and responding to them clear without requiring schema comparison.

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 explains role-based usage: page authors use 'fixed' to indicate whether a remark was resolved, while reviewers or project leads use 'action' to reopen or withdraw a remark. This gives clear conditions for selecting each parameter path and names the related sibling tool for retrieval.

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

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

Annotations only declare it is not read-only, not destructive, not open-world; the description adds far more: the version acts as an optimistic lock and the call is refused on a stale read, the approval is an append-only journal line that is never edited or deleted, later page edits do not erase it but re-mark the approved edition, and the exact authorization set (project lead, company owner, admin, or person named via ask_wiki_page_approval).

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

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

Front-loaded with the verb and identity constraint, and every sentence contributes (concurrency, immutability, authorization, intent). Slightly long and the closing maxim is rhetorically weightier than necessary, but nothing 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?

No output schema exists, yet the description covers what the side effect is, who may perform it, what invalidates the call, and how to undo it — everything an agent needs to invoke it correctly and safely.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning the schema does not: 'version' is specifically the value get_wiki_page returned and functions as a concurrency guard that causes refusal, and 'note' is framed as the recorded rationale that persists with the journal line.

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+resource ('Approve a wiki page') and immediately pins the scope: 'IN YOUR OWN NAME, in the edition you read'. It is also clearly distinguishable from the sibling approve-adjacent tools (withdraw_wiki_page_approval, ask_wiki_page_approval) which it names.

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

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

Gives explicit when-to-use ('do it when your person told you to, not because a page looks finished') and a when-not/exclusion, plus the prerequisite 'read it again first' if the page changed. It also names withdraw_wiki_page_approval as the reversal path and ask_wiki_page_approval as the route to being named on the page.

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

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

Annotations mark this as a non-destructive write with no open-world access, so safety is largely covered. The description adds real behavioral context beyond that: it appears as an ordinary comment, is tracked in a Questions list until answered, requires comment permission, and what the deadline does with and without defaultOption. It doesn't say what happens on withdrawal or how the asker is notified, but the added context is substantial.

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

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

Purpose is front-loaded in the first clause, then behavior, then permissions and the sibling caveat. It is dense but each sentence carries information; the closing NOTE is slightly long but earns its place by preventing confusion with the background-agent ledger 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 write tool with no output schema, the description covers what is created, who sees it, tracking, permission requirements, and deadline semantics — enough to invoke correctly. Minor gaps (notification behavior, withdrawal outcome) remain but are not essential to a correct call.

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 all seven parameters are already documented and the baseline is 3. The description adds motivation rather than restating syntax — explaining that defaultOption plus the deadline lets a blocked run resume, and that the deadline only stops waiting when no default exists — which clarifies the intent of the most consequential parameter.

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

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

States a concrete verb and resource (ask one person a question with pre-written answer options in an issue thread) and immediately distinguishes it from a plain comment ('tracked separately', counted in the Questions list). An agent can tell exactly what it creates and how it differs from the comment-stream siblings without opening the schema.

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

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

Gives clear context for use ('the way to get a decision that does not get lost in the comment stream') and steers the ttlHours/defaultOption choice (defaultOption lets a blocked run continue; ttlHours 0 rarely what an agent wants). It distinguishes from the bgs 'ask_question' tool but does not explicitly name the closer siblings answer_issue_question / withdraw_issue_question, so routing guidance is clear but not exhaustive.

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

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

Beyond the annotations, the description discloses the notification side effect ('they get a notification that opens the page'), the re-ask behavior ('about the edition the page is at now'), and the non-revoking semantics of release. It adds no detail on permission failures or what happens when an entry cannot read the page.

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

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

The purpose is front-loaded in the first clause and every sentence carries non-redundant information. Some sentences, such as 'Somebody already named is asked again, about the edition the page is at now', are densely phrased enough to slow comprehension.

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

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

For a 4-parameter write tool with no output schema, the description covers permissions, side effects and both modes. It stops short of describing failure behavior and whether re-asking clears earlier approvals, which an agent might need 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?

The schema documents all four parameters fully (100% coverage), and the description still adds constraints the schema does not: the 'a,b' format, the list_users source, the read-access prerequisite, and the precise meaning of release. The only gap is the lack of detail on the 'note' 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 opens with a concrete verb and resource: it names the approvers of a wiki page and notifies them. It does not explicitly contrast itself with the sibling tools approve_wiki_page, withdraw_wiki_page_approval or set_wiki_page_readers, so an agent must infer the boundary from the name alone.

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

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

It gives clear operating conditions: 'who' must be able to read the page, entries come from list_users, and 'release: true' switches the tool into removal mode. What is missing is routing to withdraw_wiki_page_approval, which overlaps with the release path, so the agent gets no explicit 'use X instead' rule.

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

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

Goes well beyond the annotations by disclosing real side effects: a history line, watcher notices issued in the caller's name, and that concurrent description edits are not lost. It also documents idempotency ('Ticking a ticked item changes nothing') and the failure semantics for unknown ids, which annotations like destructiveHint cannot convey.

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

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

Front-loads the action and the id source in the first clause, then layers side effects, idempotency, and error handling in a tight sequence. Dense but each sentence carries distinct operational information; only the em-dash aside on concurrent edits is slightly ornate.

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 action, identifier source, permissions, side effects, idempotency, stale-id recovery, and the 'changed' false return value, which substitutes for the absent output schema. 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the id's provenance and lifecycle (rewritten or removed items make ids stale) and the no-op behavior when 'checked' matches current state.

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

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

States a specific verb pair (tick/untick), the exact resource (one checklist item), and the identifier source ('id' from get_checklist). An agent can distinguish this from get_checklist and from issue-editing tools without opening any schema.

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

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

Gives clear preconditions ('Requires permission to edit the issue') and a recovery path when the id is stale ('read the checklist again'). It does not name an explicit alternative tool or a when-not-to-use case, but the operation is narrow enough that few exist.

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

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

The description is rich about behavior (status transitions to 'api'/'mismatch'/'silent', preservation of human-verified/mismatch word as 'serviceNote', 'newerVersion', rate limits, cache). However it clearly describes live calls against open services (arXiv, Crossref, zbMATH), which contradicts the openWorldHint=false annotation. The destructiveHint=true annotation is loosely consistent with its field mutations.

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

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

The purpose is front-loaded, but the text is a dense run-on of special symbols and rules ('†', 'silent', 'newerVersion') that is longer and harder to parse than it needs to be. Every clause is relevant, but structure could be tighter.

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-mutating tool with no output schema, the description explains outcomes thoroughly (api/mismatch/silent/serviceNote/newerVersion) and permission/rate behavior. The only gap is a precise account of what the response actually contains, but the outcome semantics are covered.

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 all three parameters (id, source, project) are already documented, and the description adds no syntax or format details beyond that. Baseline 3 applies when the schema carries the load.

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?

It states a precise verb+resource (registers a source against arXiv/Crossref/zbMATH and reports agreement) and distinguishes this verification action from siblings like get_source (read), set_source (edit), and list_sources (list). An agent can identify exactly what the call does without opening the schema.

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

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

Explicitly tells the agent to call only 'when the person wants it now' since sources are checked automatically on write and weekly, and states rate limits (30/project/hour, cached a day) and the write-permission prerequisite. This is clear when-to-use guidance plus constraints.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantive behavior: the † marker appears while a reference is unchecked or disagrees with what it names, and 'found'/'offer' describe the miss path. The only gap is it doesn't clarify output shape/format of the returned BibTeX or reference beyond naming 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?

Front-loaded with the core purpose and the output contract, and every clause carries information about return values or the miss path. It is dense and runs long with nested quotes and em-dashes, which slightly slows parsing, but nothing is padding.

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

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

For a 2-parameter read-only tool with no output schema, the description fully covers what comes back (cite token, page/comment reference line, bibliography line with † flag, BibTeX), the not-found case, and the follow-up action. Nothing an agent needs in order 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, and the description earns extra credit by giving concrete identifier shapes ('arXiv:2301.01234', DOI, 'MR1234567', 'Zbl 1234.56789', ISBN) that the terse schema wording ('in any shape') does not illustrate. It falls short of 5 only because the project parameter gets no elaboration.

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 ('cite') and resource (a work in a project's register), and enumerates exactly what it returns: the 'cite' token, the reference line, and the BibTeX entry. It is easily distinguished from siblings like get_source or list_sources because it is about producing citation strings, not fetching records.

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 says to use it 'rather than typing a reference out by hand,' and names the alternative path: when 'found' is false and an identifier was given, call set_source with that identifier, a key and a title before citing. Both the when and the when-not are covered with the sibling to use instead.

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

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

Annotations already declare readOnly/destructive=false and openWorld=false, and the description adds real context beyond them: the depth ceiling of 3, that bare-name-only links are counted but not listed, and that name collisions produce a disambiguation list instead of a graph. What's missing is any note on result volume or how large the caller/callee list can get at depth 3.

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

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

Three sentences, front-loaded with the core capability, then the caveats about bare names and name collisions. Dense but each sentence carries information; the only slight redundancy is re-stating the depth limit already covered in 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?

With no output schema, the description does the work of describing returns: each call site with its file and line, counts for bare-name-only links, and a disambiguation list for name collisions. For a 5-parameter, local-only read tool with annotations covering safety, nothing essential is missing.

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

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

With 100% schema coverage the baseline would be 3, but the description adds interpretation the schema does not: 'depth' is framed as 'rings out' from the symbol, 'direction' as callers (default) vs callees, and the bar-name/ambiguity rule explains when 'path' is actually needed. That is meaningful semantics beyond the already-documented fields.

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: traversing the call graph ('who calls' / 'what it calls') for a class, method or function. It is clearly distinguishable from siblings like code_symbols, search_code and read_code, and names its scope (depth up to 3, file and line per use).

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 solid context on when the result is usable ('a bare name works when only one symbol has it', and ambiguous names cause a list to choose from), which implicitly tells the agent when to retry with path or a qualified name. It stops short of explicitly routing between this tool and search_code or code_symbols, so no named alternative appears.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: the visibility constraint that only repositories whose owners opened them to agents are queried, and the shape of the returned data (file, line, signature). Pagination and result-limit behavior remain 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?

Two sentences with no padding, and the core purpose is front-loaded before the access caveat. The final clause about repository owners is slightly convoluted in phrasing but earns its place as scope information.

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

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

With only three parameters, full schema coverage, annotations covering safety, and no output schema, the description supplies the missing pieces an agent needs: what is returned and which repositories are searched. Ambiguity handling (multiple matches, default repo scope) is the only notable omission.

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

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

Schema coverage is 100%, so the schema already documents all three parameters including the 'Class.Method' whose-form and the path/repo filters. The description's 'Ask by name, or Class.Method to say whose' largely restates the schema. Baseline 3 applies when the schema carries the parameter load.

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 resource and verb: locating where a class, method or function is *declared*, and returns file/line/signature. That is meaningfully narrower than search_code or read_code. It stops short of naming a sibling to differentiate against, leaving the agent to infer the boundary.

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

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

'Ask by name, or Class.Method to say whose' explains how to call it, not when. There is no explicit contrast with search_code, code_calls, list_code or read_code, so an agent must infer that this is the declaration-lookup tool rather than a text search or call-graph tool.

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

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

With annotations only declaring readOnly=false/destructive=false/openWorld=true, the description supplies the real behavioral burden: no token is ever accepted here, non-public repos fail with a prompt to connect via token, already-connected repositories are marked rather than duplicated (idempotency), and the operation is journaled. It also names the authorization roles (project lead, board admin, company admin).

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

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

The core action is front-loaded in the first clause and every subsequent clause carries distinct information (token policy, idempotency, permissions, journaling). It is dense and heavy on em-dashes, but nothing reads as 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 mutation tool with no output schema, it covers authorization, failure mode (private repo refusal), idempotency, side effects (journal entry), and the meaning of the optional flag. An agent has enough to call it correctly and predict the outcome.

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 meaning beyond it: 'marking opens nothing by itself' clarifies openSource is a bookkeeping flag, and it ties openSource to the downstream set_project_public requirement. This is genuine value added over the schema's own wording.

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 with scope ('Connect one more GitHub or GitLab repository to a project, by its address') and clarifies that only one repository is added at a time. An agent can immediately tell this is an additive connect operation rather than the toggle (set_repository_open_source) or listing (list_repositories).

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

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

Gives clear context: public repositories connect at once, private ones are refused and routed to a token screen, and openSource should be set only when the repo is the project's open source repository (which set_project_public depends on). It stops short of explicitly naming set_repository_open_source as the alternative for changing the flag later, so it is strong but not exhaustive.

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

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

Beyond the annotations, the description discloses key non-obvious behavior: direct chats are unique per pair and found rather than made ('created' false), agent chats are found if one exists, and project chats are never created. It also states the caller becomes administrator for group chats and that only company people are valid.

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: it states the action, then handles each kind in turn, then closes with the project-chat exception. Every clause carries operational meaning without 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?

With no output schema, the description still discloses the important return behavior ('created' false when an existing chat is found) and covers all valid kind-specific paths plus the project-chat exclusion. An agent has enough context to choose this tool and 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 the schema already documents each parameter. The description still adds useful semantics by tying parameters to kinds and clarifying that group 'members' are besides the caller, who becomes administrator, and that direct chats are one per pair.

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 ('Open a chat') and then differentiates all three supported kinds. It distinguishes creation from lookup behavior for direct and agent chats and from project chats, which are never created here.

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 conditions for each kind: 'direct' with one colleague, 'group' with title/members, 'agent' with an agent handle. It also routes the project-chat case away from this tool by naming list_chats with projectKey as the way to find it.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantially more: exactly which fields become publicly visible (kind, number, title, statement, formulas, status) and which never do (bases, journal, review), that the underlying page is exposed only while the project is public, that write permission is required, and that a history line is recorded. This is exactly the disclosure needed for a tool that publishes unauthenticated 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?

Purpose and the exposure constraints are front-loaded and nearly every clause carries information (visibility rules, output forms, identification, permissions, audit). The single run-on paragraph and archaic diction ('a link anybody can open', 'which open the claim in a cloud') make it denser to parse than it needs to be.

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

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

With no output schema, the description still explains the return values (script once per page, mark around words, iframe card), covers permissions and side effects, and leaves parameter rules to a fully documented schema. Remaining minor gaps: no statement about precedence when both id and project/label are supplied, and no hint about revoking an embed (delete_registry_embed/delete paths) after creation.

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 id/days/label/sites/project including the 'or name it by project and label' rule. The description restates that identification rule and only adds a cross-reference ('as for create_term_embed'), which is a pointer rather than new semantics, so the baseline 3 applies.

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

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

States a concrete verb and resource: it puts one claim of a project on other sites as an embeddable link, and names the three output forms (script, mark, iframe). It is distinguishable from create_term_embed/create_wiki_embed/create_embed_set by the 'claim' subject, though the ornate phrasing ('Put one claim ... on other sites') slows recognition of the exact 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?

Gives a permission precondition ('Only for somebody who may write in the project') and defers parameter behavior to a sibling ('sites' and 'days' as for create_term_embed). It never states when to use this over create_embed_set or the other create_*_embed siblings, so the routing decision is only implied by the resource name.

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

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

Annotations only say non-read-only, non-destructive, closed-world; the description goes far beyond with the access model (token holder, 'readers', the project lead who reads every secret, nobody else), the two write modes and their consequences, that the stored value is never returned, that it is attributed to the current token, and the failure path for unknown readers in 'dropped'. This is exactly the context an agent needs before calling a credential-writing 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 most important fact (what the tool is for and why not to use a comment) is front-loaded in sentence one, and the security instruction about not echoing the value is repeated at the end where it matters. It is long, and a couple of clauses are more exhortative than informative ('a value that passes through you stays in your context and in your client's logs'), but almost every sentence carries decision-relevant 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?

There is no output schema, and the description covers exactly what would be missing: the shape of the response in both modes ('form' link versus id and name, never the value), the 'readableBy' field and how to report it to the user, and 'dropped' with its reason. Permissions and partial-failure behaviour are also stated, so nothing needed to call or interpret this tool is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: it says to pass issueKey or pageId (the schema marks neither as required, so this clarifies the actual requirement), what happens when 'value' is omitted versus supplied, and that 'readers' entries may be silently dropped with a reason. That is genuine interaction semantics beyond the per-field schema text.

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

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

Opens with a concrete verb+resource: attach a secret (password, key, test login) to an issue or a wiki page. It explicitly distinguishes itself from the obvious alternative behaviour (writing the value in a comment or description), so the agent understands it is a dedicated secret store rather than a generic write.

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

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

Gives an explicit routing rule away from siblings ('instead of writing it in a comment or a description'), plus a strong preference rule for the omitted-'value' form flow 'whenever the value is not already in the conversation', and a prerequisite ('Needs the right to edit the issue or the page'). Both when-to-use and when-to-prefer-the-alternative-path are stated.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses real behavior: hard quotas (200 things per set, 20 sets per project), atomic all-or-nothing creation ('the first that is not is the refusal and nothing is made'), disclosure scoping ('Only what the list names goes out', an unknown name leaks nothing of the project), the absence of a preview card, and an audit entry in project history. The phrasing is oblique in places, but the operational facts an agent needs are present.

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

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

Purpose is front-loaded, but the body is a dense run-on of em-dashes, parentheticals and elliptical clauses ('a name not on it says so and nothing of the project') that require re-reading. The PM-1167 ticket reference and meta-commentary like 'A set has no card' spend words without adding decision value.

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

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

For a 6-parameter, non-readonly write tool with no output schema, the description covers authorization, quotas, failure atomicity and disclosure scope, which is the bulk of what matters. The one gap is that it never states what the call returns (presumably the set's link/identifier), which an agent would need 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 3 is the floor; the description exceeds it by explaining that 'terms' accepts ids, words or spellings and 'claims' accepts ids or labels, comma-separated, and by cross-referencing create_term_embed for the semantics of 'sites' and 'days'. The added rule that each listed item must be individually publishable ('a confirmed term you may open') is meaningful validation context not present 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 opening clause gives a concrete verb and resource: putting a list of a project's terms and claims on other sites under ONE link, with the HTML snippets (data-kaiku-term / data-kaiku-claim) showing what is produced. It implicitly contrasts with the singular create_term_embed / create_claim_embed siblings via 'each thing as its own link would show it', but never names them as the alternative, so differentiation is left to inference.

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

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

'for an article that cites many' gives a use-case signal, and 'Only for somebody who may write in the project' sets a permission precondition. However, it never explicitly routes an agent to create_term_embed or create_claim_embed when only one thing needs publishing, and the ticket reference PM-1167 is not actionable guidance — usage is implied rather than stated.

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

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

Beyond the annotations, the description discloses important behavioral traits: the permission requirement, the returned issue key, the meaning of 'notified' and 'unresolvedMentions', and the fact that malformed mention handles are silently stored rather than refused. That last detail is especially valuable because it warns the agent that unresolvedMentions is the only signal a mention did not land.

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 return value, then moves into permission and notification details. The 'notified' explanation is dense and somewhat convoluted, but it carries genuinely important behavioral information rather than 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 12-parameter creation tool with no output schema, the description does well: it explains the return key, notification side effects, and permission requirements while the schema handles parameter details. It does not cover failure modes such as invalid project keys or issue type mismatches, which would strengthen completeness.

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 12 parameters thoroughly. The description adds useful cross-cutting context about mentions and notification behavior, but it does not add per-parameter semantics beyond what the schema provides. 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 opens with a specific verb and resource: create an issue in a project visible to this token. It also states the immediate return (the new issue key), so the agent knows exactly what action is being taken and what to expect, 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?

The description gives clear context for when this tool applies: creating an issue in a project visible to the token, with the permission requirement called out. It does not explicitly name alternatives such as update_issue or find_issues, but the create action is sufficiently distinct that the guidance is practically clear.

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

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

Well beyond the annotations (which only say readOnly=false, destructive=false, openWorld=false): it discloses that the description auto-quotes authors and timestamps, that a permission-scoped backlink is always appended, that files are copied, that a «→ KEY» marker appears on the message, that filing obeys the target project's rights/rules/watchers, and that the response mirrors create_issue.

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

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

Purpose is front-loaded and there is no filler, but the prose is dense and clipped, with constructions like 'Filed as create_issue files — your rights in that project, its rules, its watchers' that cost readability for the 14-parameter decision the agent has to make.

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 what would otherwise be unknowns for a 14-parameter mutation with no output schema: side effects (file copying, message marker, backlink), permission implications, filing rules, and the response shape ('Answers like create_issue, with files copied').

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 projectKey defaulting, description/summary defaults, copyFiles, and the 50-message thread cap are already documented in the schema. The description mostly restates those behaviors rather than adding new parameter meaning, 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 and resource ('Make an issue of a message in one of the company's chats — or of a thread of them') plus the one-step scope, and names create_issue as the analogous flow so the agent can place it against the general issue-creation 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?

Gives a concrete routing rule for the main decision: 'A project's chat files into its project when projectKey is omitted; any other chat needs projectKey.' It does not explicitly compare against create_issue (e.g. 'use create_issue when not starting from a chat message'), so it's clear context without full exclusions.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false) by disclosing idempotent retry semantics (same key+name returns created:false), key-collision refusal that names the conflicting project, refusal of taken keys instead of auto-suffixing, and that openSourceRepo is host-verified without a token. The auth model for workspace admins and parent-subproject leads is spelled out.

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

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

Front-loads the authorization constraint and the key-immutability warning before the idempotency and subproject details. It is dense and fairly long, but every sentence carries a distinct operational fact; 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?

A mutating, 7-parameter tool with no output schema needs to explain the return and failure modes, and it does: created:false on retry, refusal with the conflicting project's name, and host-verification failure for openSourceRepo. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds real meaning beyond the schema — that the key is always caller-supplied and never generated, that the lead defaults to the caller and is required for later configuration, and that parentKey implies inherited access so only non-inherited people need adding.

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 ("create a project") and enumerates what gets created — a key, a starter board, a wiki space — which distinguishes it immediately from create_issue, create_project_rule and create_wiki_page. The scope (workspace-level project provisioning) 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?

Explicitly gates usage on role ("Administrators only", plus parent lead for subprojects) and explains that deletion is not available here, which routes the agent away from using this tool as a lifecycle manager. It does not name a concrete alternative for removal, so it stops short of full when/when-not/alternatives coverage.

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

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

Discloses duplicate suppression via the hidden pm-rule marker, tooLong and tooDeep failure behavior, moveRefused journal outcomes, ownership semantics for webhook and duty rules, spending caps, and permission constraints. This goes far beyond what the annotations provide.

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

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

The core behavior is front-loaded, but the bulk is a single dense paragraph covering every rare trigger and edge case. The length is defensible for an 18-parameter tool with many modes, yet grouping or line breaks would make it substantially easier to scan.

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

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

Covers all action modes, trigger edge cases, failure outcomes, ownership rules, permissions, and expected name lookup via list_project_rules. Although there is no output schema, the description explains the important side effects and journal outcomes an agent needs to understand.

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 has 100% description coverage, the prose adds important cross-parameter meaning: non-entered triggers require an empty status, move ignores template, a duty's template is an instruction rather than appended text, and fromStatus means different states depending on trigger type.

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 precise verb-resource-effect: 'Add a rule to a project: when an issue enters status, append template to its description.' It then distinguishes the three action modes (checklist, move, agent duty) and signals that action is fixed after creation, which separates it from 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?

Explicitly states the permission requirement ('Project lead or admin only'), when to pass an empty status or template, how trigger values map to situations, and that list_project_rules lists valid state and type names. It effectively guides the agent through choosing among many trigger/action combinations.

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

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

Annotations only say it is a non-readonly, non-destructive, non-open-world mutation; the description adds substantial context beyond that: what a public viewer sees, that it writes a line in project history, the authorization requirements, and the exact return artifacts ('script', 'mark', 'iframe'). This is rich disclosure an agent could not get from the annotations.

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

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

Front-loaded with the purpose before parameters, alternatives, and permissions. The single dense paragraph with heavy em-dash and parenthetical nesting makes it harder to scan than necessary, but nearly every clause carries information and nothing 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?

No output schema exists, and the description fully covers the return value (the generated embed code variants), side effects (history entry), permissions, and optional-parameter defaults. 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?

Schema coverage is already 100%, so baseline would be 3, but the description adds real meaning: 'term' accepts its word or any spelling, 'sites' takes comma-separated https origins with 'none is any', and 'days' 1-3650 with 'none is until removed'. It also cross-references list_terms for obtaining 'id'.

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: puts a confirmed term on other sites as an embeddable link, and describes exactly what the embed exposes (word, definition with formulas, source location while public). It distinguishes itself from the sibling create_embed_set explicitly ('For many terms of one article, create_embed_set gives one link for all of them').

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

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

Gives a clear condition for use (one confirmed term) and names the alternative (create_embed_set for many terms of one article). Permissions are stated ('Only for somebody who may write in the project and open the term's source'). It does not contrast with the other embed siblings (create_wiki_embed, create_claim_embed), but the resource distinction is implicit.

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

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

Goes well beyond the annotations: discloses the uniqueness constraint (name unique in project, case-insensitive), the authorization requirement (project lead or admin only), where in the sequence the version lands, and that the response matches list_versions. These are non-obvious constraints an agent could not infer from readOnlyHint/destructiveHint.

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

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

Front-loaded with the action and the key constraint; every sentence conveys something actionable. The parenthetical enumeration of fixVersions call sites and JQL examples is somewhat verbose relative to the core task, but it is informative rather than 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 5-parameter create tool with no output schema and no annotation coverage of auth or uniqueness, the description supplies permissions, uniqueness, placement semantics, and the shape of the returned object. An agent has enough 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%, so the parameters are already documented; the description still adds value by stating the name uniqueness/case rule and by clarifying that issue-level versions come from the issue's own project. It adds constraint semantics rather than restating field types.

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 ('Add a version to a project') plus a positional qualifier ('at the end of its sequence'), and defines what a version is with concrete examples. It is clearly distinguishable from update_version and release_version, the latter explicitly claimed elsewhere.

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 scopes usage by noting that a version belongs to its project and that any number of them can be attached, and it explicitly routes release behavior to release_version rather than doing it here. It does not explicitly contrast create_version with update_version, so the when-to-use picture is clear but not exhaustive.

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

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

Adds substantial context beyond the annotations: the link is public with no account, exposes only the scene and caption, returns both a link and ready <iframe>, follows subsequent block edits, requires page-edit permission, and writes a history entry. These details materially improve safe invocation.

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

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

Purpose and response format are front-loaded and every sentence carries information, but the description is long and repeats some schema detail such as sites/days/caption behavior. It could be trimmed without losing essential meaning.

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

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

Despite no output schema, the description explains the return payload (link and iframe), permission requirements, history side effect, edit propagation, and removal path. An agent has enough information to call the tool correctly and understand its effects.

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 meaning by tying 'block' to get_wiki_page's 'anims' numbering and explaining the 'anim' vs 'anim-js' language distinction. However, sites, days, and caption largely restate the schema 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?

States a specific verb ('Put'), resource ('one scene of a wiki page'), and target ('other sites'), and immediately clarifies what the resulting link exposes and withholds. This clearly distinguishes creation from update_wiki_embed, delete_wiki_embed, and list_wiki_embeds.

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 the core use case and a permission gate ('Only for somebody who may edit the page'), plus names delete_wiki_embed as the removal alternative. It does not explicitly contrast with update_wiki_embed for modifying an existing embed, but the guidance is otherwise clear.

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

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

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses the return payload (new page id and URL) and, crucially, that a wrong mention handle is stored as written and never refused, so 'unresolvedMentions' is the only signal of failure. It also flags that the anim block answer reports per-block playback problems — non-obvious side-effect behavior an agent would otherwise miss.

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

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

Front-loads the action and the default parent in the first two sentences before the denser Markdown/mention/anim detail. The single-paragraph block is information-dense and every clause carries operational consequence, though it is longer than needed for a create 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?

With no output schema, the description still tells the agent what comes back ('page id and URL', 'anims', 'notified', 'unresolvedMentions', 'claims'), which is exactly the completeness burden this tool carries. Combined with a 7-parameter schema already at full coverage, nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema doesn't carry: the [@Name](user:username) mention form specific to wiki pages (vs [~username] in issues), the [text](page:Title) cross-link syntax, and the ```anim block contract resolved against product_help topic 'anim'. It complements rather than duplicates 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 ('Create a wiki page from Markdown') plus a scope constraint ('in a space you can write to') and the default placement ('Hangs off the space home page unless you name a parent'). The verb 'create' clearly separates it from update_wiki_page/delete_wiki_page and the Markdown body separates it from create_wiki_embed.

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

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

Gives concrete routing rules for the placement decision: omit parent to hang off the space home page, or name one via parentId or parentTitle within the same space. It also explains the template-vs-markdown precedence. It stops short of explicit 'use update_wiki_page instead when the page exists' guidance.

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

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

Adds substantial context beyond the annotations: approval grants the reporter role with issue/comment rights, decline imposes a 14-day re-request window, both outcomes trigger an email and a company journal entry, and only the project owner/administrators may call it. These are real consequences that the destructiveHint flag alone cannot convey.

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 action is front-loaded in the opening sentence and each subsequent sentence carries a distinct consequence (role, cooldown, notification, permissions). Slightly dense with em-dash clauses, but nothing is wasted.

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

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

For a 3-parameter mutation with no output schema, the description supplies the side effects, authorization requirement, reversal/cooldown behavior, and the sourcing of the id. An agent has everything needed to call it correctly and safely.

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's framing of approve (reporter grant vs. decline) largely restates the schema's own parameter descriptions; the only added value is the pointer to list_join_requests for the id.

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

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

States a specific verb pair (approve/decline) applied to a specific resource (one request to take part in a public project). It also names where the ids come from (list_join_requests), which lets an agent distinguish it from sibling decision tools like decide_persons or decide_terms.

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 routes the agent to list_join_requests for ids and notes that broader role assignment happens on the project's people screen, implicitly steering that need elsewhere. It does not state a when-not-to-use case, but the context is clear.

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

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

Beyond the destructiveHint annotation, the description discloses important behavior: the expected count acts as a guard and nothing is written if the count has changed, write-access permission is required, and availability is gated by the company's AI plan. It also adds a human-confirmation workflow requirement.

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

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

The purpose is front-loaded, and the description is compact with no wasted explanation. A few short permission/gating sentences are terse fragments rather than polished prose, but they remain informative and easy to scan.

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

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

For a destructive batch mutation with no output schema, the description covers the key invocation details: scope, source format relation, concurrency guard, permissions, plan gating, and human confirmation. It does not describe success responses or whether decisions are reversible, but it is otherwise complete enough 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 description coverage is 100%, so the schema already defines all five parameters. The description still adds semantic value for source and expected by linking source naming to list_persons and explaining that expected is a count guard that prevents writes when stale.

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: confirm or reject every PROPOSED person of one source at once, scoped to the persons found in one page/issue/comment. It also names the related sibling list_persons, so the agent can distinguish this batch decision tool from the listing tool.

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

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

The description gives clear usage context: it is a batch decision over proposed persons of a single source, and it says to ask the person first. It does not explicitly compare against alternatives such as individual person editing or merging, but the scope and prerequisites are clear enough for correct invocation.

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

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

Goes well beyond the annotations: 'release' bypasses the spam filter and limits and matches or opens a request with an acknowledgement, while 'dismiss' drops files and deletes the row after 30 days. It also states the full-write-access requirement, and these details are consistent with destructiveHint=true.

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

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

Front-loaded and nearly every clause carries information, but the long parenthetical-heavy sentences make it denser than needed. Slight tightening would improve it.

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

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

For a destructive two-parameter tool with no output schema, it covers the effects, the permission prerequisite, and the retention consequence. It does not say what the call returns or whether the action can be undone, which leaves a small 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 coverage is 100%, so the baseline is 3, but the description adds real semantics for the 'decision' values, explaining the downstream consequences of each. The 'letterId' parameter is only covered by the schema, so it is not a 5.

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

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

States a specific verb and resource ('Decide what a held or failed letter to the support address is') and pins down the two possible outcomes. It is clearly distinguishable from get_support_letter and list_support_letters, which only read 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?

Scopes use to held or failed letters and points at list_support_letters for the id via the schema. It does not explicitly state when not to use it or name a sibling alternative for handling letters, so it falls short of a 5.

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

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

Adds real context beyond the annotations: an optimistic-concurrency guard where nothing is written on count mismatch, plus permission ('members who may write only') and plan gating ('only where the company's plan includes AI'). It does not say what 'reject' does to a term afterward or whether it can be undone, which matters given destructiveHint=true.

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

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

The core action is front-loaded and each following sentence carries a distinct rule: precondition, failure mode, safety instruction, permissions, plan gate. No filler despite the density of 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 bulk destructive mutation with no output schema, it covers preconditions, failure semantics, permissions and plan gating. The gaps are the effect/reversibility of 'reject' and the shape of the response beyond the count-mismatch case.

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 ties 'source' and 'expected' back to list_terms' output ('total' with state 'proposed'), which is helpful cross-tool guidance, but it adds nothing about 'kind' and little syntax 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 pair and resource with exact scope: 'Confirm or reject every PROPOSED term of one source at once', and anchors the behavior to a known UI action ('Confirm all on this page'). That clearly separates it from list_terms (read), set_term (single term) and decide_persons.

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

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

Gives an explicit prerequisite and workflow: read first with list_terms using the same 'source', then pass 'expected' from that read. It also states the recovery path when the count drifted ('read the list again') and a scoping rule ('Confirm only what the person asked for').

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

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

Although annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, the description goes well beyond them: it discloses filtering rules ("Only confirmed terms, and only those whose source you may open"), a licensing constraint ("Only where the company's plan includes AI"), and the 'links' relationship kinds returned. That is substantial behavioral context beyond the annotation set.

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

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

The core purpose and the when-to-use instruction are front-loaded in the first sentences, and most clauses carry real information. It is dense and slightly over-stuffed with parenthetical nesting, so it falls short of maximal conciseness, but nothing is clearly 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?

There is no output schema, so the description carries the return-value burden and does: it explains the definition, where it is defined, spelling variants, the links structure, and what an empty result means. With only two well-documented parameters, this is complete enough to call correctly.

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

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

Schema coverage is 100%, so the schema already documents 'word' and 'project'; baseline is 3. The description adds meaning beyond it by describing matching behavior ("Matches the term or any of its spellings, case aside, then terms that begin so") and the read-scope constraint, which directly clarifies how the 'word' input is interpreted.

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 concrete resource (a project's own definition of a word, code, or notion), gives examples, and explicitly distinguishes itself from the sibling 'term_graph' ("term_graph has the whole picture"). An agent can tell exactly what this returns without opening the schema.

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

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

It prescribes when to use it ("Ask it before guessing at a word you do not know in an issue or a page"), points to the alternative for the full picture, and states the fallback behavior when the result is empty ("ordinary word, or ask a person"). Exclusions and alternatives are both covered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so permanence is flagged structurally. The description adds genuine value with the edit-permission requirement and the upsert behavior of the sibling, but says nothing about what happens when the id is unknown or already deleted, or whether the removal is recoverable.

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

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

Three short clauses, front-loaded with the action and scope, then the alternative, then the permission gate. No filler and nothing an agent must skip past to act.

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 delete with full schema coverage and destructiveHint already declared, this covers action, identifier provenance, alternative path, and authorization. Only the failure/not-found behavior is left unspecified, which is a minor gap given annotations carry the safety profile.

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 both parameters are self-documenting ('Record id, as returned by get_agent_usage'; 'Issue key, e.g. UK-1'). The description's mention of the id source essentially restates the schema, adding no format or edge-case detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove one agent-usage record from an issue') plus the exact identifier source ('by the id that get_agent_usage returns'). That distinguishes it cleanly from its nearest siblings, get_agent_usage and report_agent_usage, without needing to open either schema.

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

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

Explicitly routes the correction use case away from this tool: 'For correcting a record's numbers, re-send it with report_agent_usage instead — the same source + externalId updates in place.' It also names the precondition ('Requires permission to edit the issue'), so both the alternative and the gate are stated rather than inferred.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower. The description still adds real value beyond them: it discloses the authorization requirement ('requires permission to edit issues in that project') and the prerequisite lookup step, which the annotations cannot express.

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

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

A single sentence that leads with the action and resource, then the identifier options, then the permission constraint. No filler and nothing buried.

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

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

For a 3-parameter mutation with no output schema and annotations that already flag destructiveness, the description covers the key agent needs: which identifiers to use, where to get them, and the permission gate. Only edge-case behavior (supplying both id and filename, or a missing file) is left unaddressed.

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 reinforces that filename and id are mutually exclusive identifiers and reiterates their provenance from get_issue, but that provenance is already stated in the schema descriptions, so it adds little beyond structured data.

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 ('Remove a file from an issue') and names the two accepted identifiers. Scoping the removal to an issue implicitly separates it from delete_wiki_attachment, but no sibling is named explicitly.

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

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

The description tells the agent where the identifiers come from ('both come back from get_issue') and states a permission prerequisite, which is useful context. It does not state when to prefer this over alternatives such as delete_wiki_attachment, nor what happens if both id and filename are supplied — usage is only implied.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond that by explaining that words and files disappear for everybody, that a «deleted» placeholder remains so replies still resolve, that the action is irreversible, and that it is restricted to the caller's own messages. This is exactly the operational context an agent needs before invoking a destructive tool.

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

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

A single front-loaded sentence covering effect, side effect, irreversibility, and permission, with no filler. Every clause carries distinct 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 destructive tool with no output schema, the description covers consequences, persistence semantics, and authorization scope. It omits only what the call returns (e.g. the deleted message id or success flag), a minor 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 coverage is 100%, so the schema already documents chatId and messageId. The description nonetheless adds a real constraint on messageId — it must be a message the caller wrote — which the schema only hints at.

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 (delete) and resource (a chat message you wrote), plus an ownership scope that separates it from generic message operations. It does not explicitly name edit_chat_message as the non-destructive sibling, so differentiation is inferred rather than 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?

'As the screen does' and 'Only your own message' imply when the tool applies, and 'Cannot be undone' signals the risk profile of the choice. However, no alternative is named (e.g. edit_chat_message for corrections) and no explicit when-not guidance is given.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: irreversibility, the post-delete journal state (lines kept plus a deletion record), and the write-permission requirement. That is real consequence disclosure an agent needs before calling a destructive tool.

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

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

Front-loaded with the action and the irreversibility warning, then the alternative and the permission note — no filler sentences. The phrasing 'with what it rests on' and 'keeps it said' is more literary than precise and costs a little parsing effort.

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, no-output-schema tool with fully documented parameters, the description covers the gaps that matter: reversibility, side effects on the journal, the safer sibling for false claims, and who may invoke it. Nothing needed 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 description coverage is 100% and each of id, label, and project is documented there, so the schema carries the burden. The description only hints at the label parameter ('confirm its label with them first') and adds nothing about how id, label, and project combine, 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 and resource — 'Remove a claim from a project's register' — and immediately bounds the scope ('for good'), so an agent can tell it apart from set_claim, set_claim_status, and delete_* siblings on other resources. The only soft spot is the ambiguous clause 'with what it rests on', but the core action 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?

Gives explicit when-to-use ('only when the person asked for this very one to be deleted'), a confirmation step ('confirm its label with them first'), and a named alternative for the common adjacent intent ('A claim that turned out false is not deleted: set_claim_status refuted or retracted'). It even states the permission gate ('Members of the project who may write only').

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description contributes the permission prerequisite ('Requires permission to edit the issue'), which annotations cannot express. It stops short of stating reversibility or what happens if the id is stale, so it is strong but not complete.

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

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

Three short sentences, front-loaded with the action and scope, then the alternative, then the permission requirement. 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 two-parameter destructive tool with annotations and no output schema, the description covers action, id source, alternative path, and permissions. Error/staleness behavior is the only 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 coverage is 100% and both parameters are documented in-schema, including the id's provenance. The description's mention of 'the id list_computations gives' largely restates the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove one computation from an issue') plus the exact id provenance and the motivating scenario ('for a job reported against the wrong issue'). An agent can distinguish it from report_computation and list_computations without opening any schema.

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

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

Gives the when ('reported against the wrong issue'), the when-not ('To correct one, report it again under its own name instead'), and names the sibling used to obtain the id (list_computations). Nothing 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.

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

Beyond the destructiveHint annotation, it discloses that deletion also removes the value, reader list, and reading record, and that the action cannot be undone. It further explains who is authorized to perform the deletion, which is exactly the behavioral context an agent needs for a destructive operation.

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

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

The description is front-loaded with the destructive action and cascade, followed by authorization and the safer alternative. Every sentence contributes useful information without 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 one-parameter destructive tool with annotations and no output schema, the description covers irreversibility, cascading data loss, authorization, and the safer alternative. There are no material gaps 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?

Schema coverage is 100%, and the single id parameter is already documented in the schema as coming from list_credentials. The description repeats that source but adds no further syntax, format, or validation semantics 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?

It states a specific verb and resource: remove a credential by id. It also names the cascading effects and distinguishes the operation from update_credential, so an agent can identify exactly what this tool does among the credential-related siblings.

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

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

The description gives explicit authorization constraints: only the person who attached the credential and the project lead may delete it. It also names the alternative for a narrower access change: use update_credential's 'readers' to remove one person's access.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false. The description adds valuable behavioral context beyond those annotations: already-filed issues remain unchanged, and the action is restricted to the project lead, company owner, or admin.

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

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

Three short sentences, front-loaded with the core action and followed by the key side effect and permission constraint. Every sentence earns its place with no 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 two-parameter destructive schedule deletion with full schema coverage and explicit destructive annotations, the description supplies the missing operational context: scope, side effect on already-filed issues, and authorization requirements. No output schema exists, so return-value explanation is unnecessary.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema, including that id comes from list_issue_schedules. The description itself adds no parameter semantics beyond what the schema already provides, 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?

States a specific destructive verb ("Remove") and the resource (a recurring issue from a project), and the title clarifies that this targets an issue schedule. It is clearly distinguishable from sibling tools like list_issue_schedules and set_issue_schedule.

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 use case by saying it removes a recurring issue, and it names who may perform the action. However, it does not explicitly compare this tool with alternatives such as set_issue_schedule for updating a schedule or list_issue_schedules for viewing one.

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

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

Annotations already flag destructiveHint=true, but the description adds substance: permanence ('it cannot be undone'), the blast radius ('all their spellings and facts'), and the audit side effect ('the journal keeps a line that a person was deleted, without the name'). It also states the write-permission requirement, which annotations do not convey.

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 destructive warning and confirmation requirement are front-loaded, and each sentence carries new information (irreversibility, audit trail, alternative tool, permissions). The trailing permission clause is a fragment that would read better placed earlier, costing it a point.

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 destructive tool with no output schema, the description covers everything an agent needs: irreversibility, confirmation step, the correct alternative for proposed persons, audit behavior, and the permission gate.

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

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

Only one parameter and schema coverage is 100%, with the schema itself explaining that the id comes from list_persons. The description adds no syntax or formatting guidance for the id beyond that, 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 and resource ('Remove a person from a project's register') and adds scope detail ('with all their spellings and facts'). It also distinguishes itself from the nearest alternative by naming set_person with state 'rejected' and from list_persons as the source of the id.

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

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

Explicit when-to-use ('only when the person asked for this very one to be deleted; confirm the name with them first') and explicit when-not ('To turn down a PROPOSED person use set_person with state 'rejected' instead'), plus the authorization boundary ('Members of the project who may write only'). Nothing 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.

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

Annotations already declare destructiveHint=true, but the description adds real value beyond them: it discloses that the response reports how many issues lost a value, that the issues themselves are untouched, and that lead/admin permission is required. That is exactly the consequence-and-auth context a destructive mutation needs.

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

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

Three short sentences, front-loaded with the action, followed by the return-value explanation and the permission constraint. The parenthetical rationale ("because that number is what the decision was about") earns its place by explaining why the count matters.

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 two-parameter tool with no output schema, the description covers the action, the return value, the non-effect on issues, and the authorization requirement. An agent has everything needed to call it correctly and safely.

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

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

Schema description coverage is 100% and both parameters (name, projectKey) are documented with examples, so the schema carries the burden. The description adds no syntax or format detail about the field name beyond what the schema already 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?

States a specific verb and resource ("Remove a column from a project"), which separates it from set_project_field and list_project_fields in the sibling set. It does not explicitly name those alternatives, 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?

The "Project lead or admin only" clause gives a prerequisite for calling it, which is useful. However, there is no explicit guidance on when to delete a field versus updating it via set_project_field, nor any warning about when not to use it, so usage is only implied.

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

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

Annotations already flag destructiveHint=true, but the description adds content the annotations cannot carry: two blocking preconditions, a cascade side effect ('a rule on it goes with it'), and an authorization requirement ('Project lead or admin only'). That is exactly the extra context an agent needs before a destructive call.

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

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

Two compact sentences with no filler; the blocking conditions and the permission clause are packed in and front-loaded after the core action. Nothing could be cut without losing decision-relevant 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?

A two-parameter destructive mutation with no output schema needs exactly this: what it removes, what blocks it, what it cascades, and who may call it. All four are present, so an agent can decide correctly 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 coverage is 100%, so baseline is 3. The phrase 'of this project's own' adds real meaning to the `name` parameter, clarifying it must reference a project-scoped type rather than a shared/global one, which is not stated in the schema text 'The own type's name.'

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 ('Remove an issue type') and narrows the scope to project-local types ('of this project's own'), which distinguishes it from global-type handling. It does not explicitly name set_project_issue_type as the sibling to use instead, but the action itself 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?

Explicitly states when the call will be refused ('while any issue is of it or any field is kept for it — change those first'), which tells the agent what to do before retrying. It doesn't name the sibling tools to run for that cleanup, so it stops 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.

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

Annotations already flag destructiveHint=true, but the description goes further and describes the actual blast radius: checklists it already added persist in their issues while its journal is removed with it. It also discloses the authorization requirement (project lead or admin only), which annotations do not cover.

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

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

Three short sentences, zero filler, with the destructive effect and the non-destructive alternative front-loaded before the permission note.

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