Keelen

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful state-machine behavior: the call flips the thread back to intake_pending and enforces exactly one answer per question. It doesn't contradict any annotation.

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

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

Three tight sentences that front-load the action and precondition before the payload rules. Every sentence earns its place, though the answers formatting sentence is dense.

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?

An output schema exists so return values needn't be explained, and the description still covers the state transition and the answers payload shape. It omits any note on the identifier parameters and error handling for a wrong precondition status, so it is not fully exhaustive.

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 0%, so the description must carry parameter meaning. It does document the complex parameter well — answers is a list of {idx from get_request_status, answer_md 1..2000 chars} with an exactly-one-answer-per-question rule. project_id and thread_id are left undocumented, keeping it short of 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?

Names a specific verb (answer), resource (a thread's clarifying questions), and adds a hard precondition (status must be awaiting_answers). This clearly separates it from siblings like get_request_status (read state) and submit_request (create thread).

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?

States the precondition for calling (thread must be in awaiting_answers) and points to get_request_status as the way to observe state and obtain question indices. It lacks explicit when-not-to-use guidance (e.g. what to do if the status isn't awaiting_answers), so it's clear context without full routing rules.

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 idempotentHint=false, but the description goes well beyond them: it explains that stopping a machine DESTROYS running process state, that a replay no-ops on rows yet is 'not idempotent end to end', and that restoration keeps project + history. This is exactly the beyond-annotation context that prevents misuse.

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

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

Front-loads the core action and the reversibility caveat before the operational consequences. Every sentence (slot freeing, process destruction, replay semantics, ownership) carries distinct load with no filler.

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

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

For a destructive mutation with an output schema (so return values needn't be explained), the description covers what is destroyed, what is retained, restoration path, idempotency, and error behavior. Nothing an agent needs to call this safely 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 0%, so the description carries the burden; it adds that the key is owner-scoped and that a project not in the workspace returns 404. It does not describe the project_id's format or how to obtain it, leaving a small gap for a single required identifier.

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 ('Archive a project') and immediately frames it as a reversible shelve, distinguishing it from permanent removal. It explicitly names the sibling it is not (delete_project), so an agent can route correctly without opening 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?

Gives an explicit when-to-use rule ('preferable to delete_project unless the project must be gone') plus the conditions under which the operation applies (owner-scoped, 404 for out-of-workspace projects). The alternative sibling is named with the condition that selects 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?

Adds substantial behavior beyond the annotations: removal from the expand queue, resolution of open expand-lane escalations, a 409 refusal while expansion is in flight with retry guidance, and a business-level replay guard. There is a mild tension between the stated 'changes no state' replay guard and idempotentHint=false, but the mid-expansion refusal and restore path keep the safety profile consistent with destructiveHint=false.

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 escalation rationale are front-loaded, and each sentence carries behavioral content. It is dense and slightly long for a two-parameter tool, but little of it 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?

With an output schema present, the return-value note is redundant but harmless. Combined with the rich usage and failure behavior, everything an agent needs to call it correctly is 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 0%, so the description carries the burden. It usefully explains that list_roadmap supplies item_id, but project_id is never explained or scoped, so it only partially compensates for the coverage gap.

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 ('Cancel / close a single roadmap item') and disambiguates from siblings like list_roadmap by naming it as the id source. An agent can distinguish it from rearm_roadmap_item and archive_project 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 a concrete when-to-use: delivered or duplicate items that keep re-parking and generating recurring roadmap_item_parked escalations. It also notes the restore path via the dashboard, but does not explicitly name sibling alternatives (e.g., rearm_roadmap_item) as the not-to-use case.

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 (readOnlyHint=false, destructiveHint=false): discloses the 422 refusal on non-queued items, that in-flight/shipped items derive their pins, the side effect of repricing the queue, and the exact return fields {id, previous_pin, horizon_pin, next_step}. This is unusually rich behavioral disclosure.

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

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

Four sentences, front-loaded with the core action and effect, followed by rationale and edge cases. Nothing is wasted, though the single long parenthetical covering reorder behavior could be slightly tightened.

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

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

Given annotations that already cover the safety profile and an output schema that documents return values, the description still supplies essential missing context: preconditions, refusal code, and the relationship to reorder_roadmap and cancel_roadmap_item. Nothing material is omitted 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 0%, so the description must compensate. The two parameters (project_id, item_id) are referenced implicitly by 'item' and 'queued items', and the return shape clarifies what item_id identifies. However, explicit parameter names and meanings are never given, leaving a small gap for an agent that needs to know which identifier is which.

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?

Opening sentence gives a precise verb (clear), resource (queued roadmap item's horizon pin), and effect (now/next/later → none). The tool is clearly distinguishable from siblings like reorder_roadmap and cancel_roadmap_item, which are named explicitly in context.

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

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

Explicitly states when to use this vs alternatives: explains that reorder_roadmap cannot move a pinned item, so unpin first, and that a delivered item should be closed with cancel_roadmap_item instead. The preconditions (only queued items) and the refusal condition (422 on non-queued) are 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 destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it clarifies the soft-close semantics (marked cancelled, ALL history retained, nothing deleted), the audit-trail recording of `reason`, the 409 in-flight-iteration refusal, the cross-workspace 404, the replay guard, and the subtle end-to-end non-idempotency from persisted credential-use state. That is exactly the extra context annotations cannot carry.

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 required-parameter constraint are front-loaded, and the paragraphs are information-dense rather than repetitive. It is on the long side, and the closing motivational paragraph about planning capacity could be trimmed, but nearly every sentence carries operational 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?

An output schema exists and the description correctly leverages it by explaining the meaningful return signal (`open_tasks`, how to read an unchanged count, and its equivalence to project_status). Combined with error paths, idempotency nuances, and provenance semantics, an agent has everything needed to call this 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 0%, so the description must compensate, and it does for the non-obvious parameters: `reason` is stated as REQUIRED and audit-trail-recorded, and `superseded_by_pr_number`/`superseded_by_task_id` are explained as verified provenance instead of a bare abandon. `project_id` and `task_id` are left unexplained, but they are self-evident identifiers.

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

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

The opening sentence names a specific verb and resource plus the exact subclass of tasks it applies to ('a task that should not be built — a duplicate, or work already shipped'). This clearly separates it from siblings like replan_task, retry_blocked_task, and cancel_roadmap_item, which address different lifecycle states.

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 when-to-use ('obsolete: the change already landed in another PR, a sibling task covers it, or the user changed direction'), a when-not (a task under a running iteration refuses with 409, and cross-workspace tasks 404), and the alternative path ('those are delivered or re-planned separately'). The final paragraph adds the positive reason to prefer closing over leaving a dead task.

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds meaningful context beyond them: the 10-minute expiry of the link and that a repeat call mints a fresh one. This is exactly the sort of state information an agent needs when retrying.

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 purpose, then behavior, then verification path. The phrase 'so work can reach real repos' is slightly decorative but supports intent; nothing else 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?

Despite having an output schema, the description explains the key return value (install_url) and its lifecycle, plus the follow-up verification tool. Nothing an agent needs to invoke 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate beyond the empty schema.

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

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

States a specific verb and resource ('Get the link that connects a GitHub account') and names the artifact returned (install_url). It is clearly distinguishable from siblings like list_github_repos and get_onboarding_status.

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

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

The description explains the flow: user opens install_url, approves, lands on a connected page, after which get_onboarding_status() reports github_connected true. That clearly frames when to call it, though it doesn't state explicit exclusions or when not to call 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 already declare destructiveHint=true, non-idempotent and openWorld, but the description goes further by warning that enable/resume can execute refinement that DELETES tasks and that process_now starts an intake batch, and that the operation is destructive even when the echoed scheduler state looks unchanged. This is exactly the non-obvious behavioral context 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?

The lead sentence states the purpose up front and the bulleted action list is well-structured and scannable. Slightly dense, but nearly every sentence conveys distinct operational 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?

With an output schema present, the one-line 'Returns the resulting scheduler state' is sufficient. Combined with the destructive-action warnings and annotation coverage, an agent has everything needed to invoke this 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 0%, so the description must carry the parameter burden. It fully documents the `action` parameter's four allowed values and their effects, though it adds no information about `project_id` beyond its obvious 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 verb set (start, pause, resume) applied to a named resource (a project's autonomous work / scheduler), and enumerates the four distinct `action` values so an agent knows exactly what the tool controls. It is clearly distinguishable from siblings like archive_project or replan_task.

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 per-action conditions: enable/disable flip scheduler_enabled, resume clears a peak/backoff/manual pause, and process_now acts independent of the dev scheduler switch. It does not explicitly name alternative sibling tools to use instead, but the routing between the four actions is unambiguous.

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

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

Annotations already flag destructiveHint/idempotentHint/openWorldHint, and the description adds substantial non-obvious behavior: the repo is created via whichever member holds repo-create OAuth access (or the chosen org), an actionable error results if none exists, unregistered CI labels are rejected rather than queued, and on scaffolding failure best-effort compensation deletes the just-created repo. This goes well beyond what the annotations provide and is internally 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 purpose followed by sibling routing, then per-parameter detail, then return/error behavior — a sensible order. The opening 'Start building something new:' is mild filler and the parameter section is dense, but at 0% schema coverage nearly every sentence earns its place, so only minor trimming 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 a 9-parameter, non-idempotent, open-world mutation with an output schema, the description covers prerequisites (repo-create OAuth access), failure modes (missing credential, invalid CI labels, framework/kind mismatch, failed submit with a next_tool directive), and the follow-up action (poll get_request_status). 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 0%, so the description carries the full burden and does: it enumerates the project_kind values, the engine values with credential preconditions, the web_app-only framework values, the conditional requirement that preview_command is set iff project_kind=='web_app', the ci_runs_on label format and validation, and the default/meaning of org and private. This fully compensates for the undocumented 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 ('creates a GitHub repo and begins work on it') and immediately distinguishes itself from the closest sibling by name ('Given an existing repo, import_project(repo_full_name) is the right call'). An agent can tell it apart from import_project, list_github_repos, and list_projects without opening any schema.

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

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

Explicit when-to-use ('For a NEW repo'), explicit when-not ('this one would create a second, empty repo beside it'), and it names the alternative call with its argument signature, plus a browsing sibling for discovery. 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 and idempotentHint=false, and the description adds substantial context beyond them: stops in-flight machines, frees a cap slot, purges review artifacts permanently while retaining the audit row, re-import restores the row in place, and a replay changes no row. It also discloses owner-scoping and 404 behavior.

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

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

Front-loaded with the core operation and its slot-freeing effect, then layers consequences. The density of parentheticals and backticked states makes it heavier than necessary, but nearly every clause carries distinct behavioral 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 single-parameter operation with an output schema already documenting returns, the description covers the full decision surface: reversibility, artifact loss, audit retention, idempotency, scoping, and error behavior. Nothing an agent needs to call it safely 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 0% on the single project_id parameter, so the description must compensate. It clarifies owner-scoping and that a non-workspace project 404s, which adds real meaning, but gives no ID format or example, so it only partially fills the gap.

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 ('Soft-delete a project') and immediately scopes it against the sibling alternative ('the harder option', 'unlike archive_project'). An agent can distinguish it from archive_project and list_projects 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?

Explicitly names archive_project as the softer alternative and contrasts the trade-off ('there is no in-tool restore' vs. re-import restoring the row). It conveys clear usage context but never states a crisp 'use this when X / avoid when Y' rule, so a 4 rather than 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?

Annotations declare readOnlyHint=false and idempotentHint=false, so the agent knows this is not a pure read, and the description explains why: it can mint a checkout session and its output varies by subscription state. It also discloses the async unlock via Stripe webhook and the past_due no-checkout rule, which are real behavioral traits beyond the annotations. It stops short of stating explicitly that calling it creates a Stripe session.

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

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

Front-loads the core purpose, then branches into per-state behavior in a tight paragraph. Dense but nearly every clause carries state-machine detail; only the parenthetical asides add mild 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?

An output schema exists, so return values need not be re-explained, yet the description still clarifies the semantics of checkout_url, next_action, and next_step across states. For a state-dependent billing tool with a non-read-only annotation profile, an agent has everything needed to call it and interpret the result 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 0% and the single `plan` parameter has no enum in the schema, so the description carries the full burden. It does so by enumerating the allowed values (starter | pro | agency) and the default (starter), adding genuine meaning over the schema.

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

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

States a specific verb+resource (billing status) and immediately adds the second capability (Stripe checkout link when a new subscription is needed). This distinguishes it from siblings like signup, get_provisioning_status, and get_onboarding_status without opening any schema.

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

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

Gives explicit state-based guidance: checkout_url is returned for open-signup unpaid, churned, or free/trial-converting workspaces; a past_due workspace gets no checkout and must fix the card in the dashboard. It also says blocking on webhook completion is unnecessary. It does not name sibling tools as alternatives, which keeps it just short of a 5.

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

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

The description explicitly calls this a 'read-only tool', while the annotations declare readOnlyHint=false — a direct conflict about whether state can be modified. Despite otherwise helpful disclosure (grouping by evidence class, not_determinable/outside_review_scope qualifiers, disclaimer_md handoff requirement), the contradiction is serious enough to anchor this dimension at 1.

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?

Short titled paragraphs, front-loaded with what the tool returns before the parameter and availability notes. Slightly more prose than strictly necessary (the empty-group caveat and disclaimer sentence are long), but every sentence carries non-obvious 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?

An output schema exists, so return values need not be re-specified, yet the description still usefully explains the grouping semantics, qualifier fields, and the disclaimer_md obligation. The one real gap is the failure to reconcile its 'read-only' claim with the annotations.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: limit's default of 25 and cap of 100, and include_all's inclusion of resolved/dismissed/out-of-scope records. Only project_id is left unexplained, which is self-evident from the name and required list.

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

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

The opening sentence gives a specific verb (read) and resource (a project's security-control observations and review boundaries), which cleanly separates it from the mutating sibling run_control_gap_review. It stops short of naming that sibling explicitly, but the read/compute split is inferable.

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 conveys operational context (limit default/max, include_all behavior, availability after the project's trigger closes) but never states when to prefer this over run_control_gap_review, which is the obvious alternative sitting in the sibling list. Usage is implied rather than routed.

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

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

The description claims the tool is 'Read-only, no compute, no rate limit,' but the annotations declare readOnlyHint=false, directly contradicting that claim on the same axis. Although the description otherwise adds rich behavior (no rate limit, availability while the trigger is closed, the required disclaimer_md disclosure), the explicit contradiction with the annotation forces a 1.

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 one-line purpose before explaining return shape, ordering caveats, and parameters. It is on the longer side, but each sentence carries distinct information (exposure_order semantics, not_determinable, disclaimer_md, limit/include_all), with little 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?

Even though an output schema exists, the description usefully guards against misreading (exposure_order is an order, not a score; not_determinable must be surfaced; disclaimer_md must reach the user). The one completeness wart is the 'Read-only' claim that conflicts with the readOnlyHint annotation, which could mislead an agent about the tool's side 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 description coverage is 0%, so the description must carry parameter meaning, and it does: 'limit defaults to 25 (max 100)' and 'include_all adds resolved, dismissed, and out-of-scope rows to the default actionable set.' Only project_id is left unexplained, but its meaning is self-evident as a required identifier.

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 ('Read a project's legal exposure findings, worst exposure first') and implicitly distinguishes itself from run_legal_exposure_review by noting it 'works even while the trigger is closed for the project.' An agent can tell this is the read side of the legal-exposure pair without opening the schema.

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

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

The description gives clear context for when this is useful (reading findings, even when the review trigger is closed) and explains that include_all widens the default actionable set. However, it never explicitly names run_legal_exposure_review as the tool to start a review or states when NOT to call this, so routing 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?

With annotations present, the description adds substantial context beyond them: the authority of next_action, the tool's polling semantics, the deprecation window for next_action_detail, and the presence of a usage/capacity block. It does not explain why the annotations mark this status check as non-read-only and non-idempotent, which is the one unexplained behavioral wrinkle.

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 authoritative field, then organized into terse per-step bullets. The parenthetical deprecation note is verbose but carries real migration value, so it earns its place; overall density is high with little waste.

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

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

For a zero-param status tool with an output schema, this covers everything an agent needs: what is reported, how to interpret next_action, which sibling to call at each step, and the re-poll requirement. Return-value detail is correctly left to the output schema rather than duplicated.

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 per the rubric the baseline is 4. The description appropriately spends no space on parameter documentation and instead clarifies the shape of the returned next_action/next_tool 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?

The description names a specific verb+resource (check onboarding/setup status) and enumerates exactly what is reported: engine_connected, github_connected, project_count, payment_status, next_action, and a usage block. It is clearly distinguishable from siblings like get_provisioning_status or project_status by scoping itself to onboarding progress.

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 polling pattern explicitly ('polled between steps'), explains that next_action is authoritative, and maps each onboarding step (engine, github, project, launch) to the sibling tool the agent should call next. It also states the caller must re-check because the server does not push — an unusual but valuable usage constraint.

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 are thin here (readOnlyHint=false, idempotentHint=false add little for what is plainly a read), so the description carries real weight and delivers: the destructive whole-document replacement semantics of the paired writer, the risk of silent data loss, the None value when no goal exists, and tenant scoping that 404s for out-of-workspace projects. That is auth/tenancy and data-loss context beyond the 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?

Purpose is front-loaded, followed by the write hazard, the return shape, and the scoping constraint in a logical order with no filler sentences. The read-modify-write clause slightly restates the preceding sentence about whole-document replacement, which keeps it just short of ideal.

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

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

For a one-parameter read tool, the description covers purpose, the critical interaction with its setter, the return fields, the empty-state value, and cross-tenant behavior. Although an output schema exists, the description still names the fields without bloating, and nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 0% for the single project_id parameter, so the description must compensate. It adds the meaningful tenancy constraint (a project outside the caller's workspace 404s), but never states project_id's format or how to obtain it, leaving half the semantic burden unmet.

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 ('Read a project's current product goal') and immediately characterizes what a product goal is ('the outcome work is aimed at'), which implicitly separates it from get_product_vision. It also names the paired writer, set_product_goal, so an agent can tell the read from the write without opening 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?

Gives a concrete when-to-use rule: a write without a prior read silently discards existing content, so you must read before you set, and adding a line requires read-modify-write. That is strong context, but there is no explicit guidance about when NOT to use this versus the sibling get_product_vision, only versus the setter.

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 frames this unambiguously as a read ('Read a project's current product vision'), while the annotations declare readOnlyHint=false and idempotentHint=false, i.e. a potentially state-mutating, non-repeatable operation. That is a direct contradiction between stated behavior and the structured safety profile, which is exactly the case the rubric scores 1 for, regardless of how much other useful context the text supplies.

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, front-loaded paragraphs: purpose first, then the read-before-write rationale, then return shape and scoping. Every sentence carries non-redundant information and nothing is 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 single-parameter getter with an output schema, the description still adds the return shape ({project_id, product_vision_md, updated_at}), the None-when-unset case, and the tenant-scoping failure mode. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0% for the single `project_id` parameter, so the description must carry the meaning. It partially does: 'Tenant-scoped: a project not in the caller's workspace 404s' tells the agent the id must belong to the caller's workspace and what happens on mismatch, but it says nothing about id format or where to obtain it (e.g. `list_projects`).

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

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

States a specific verb (read) and resource (a project's current product vision), and glosses the resource in plain terms ('what the product is for'). It also names the paired sibling `set_product_vision`, so an agent can distinguish the getter from the setter without opening 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 usage: the paired setter replaces the whole document, so a write without a prior read silently discards existing content, and editing means read-modify-write. That is a concrete when-to-use and when-not-to-write-blindly instruction, not just implied context.

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

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

Discloses behaviour well beyond the annotations: it warns the tool is not a pure read (reaching 'ready' persists onboarding-completion state), matches readOnlyHint=false and idempotentHint=false without contradicting them, and adds poll timing, error_kind semantics, and tenant-scoping 404 behaviour.

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

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

Front-loads the core purpose, then layers state-specific next_action guidance. Dense and mostly waste-free, though the run-on enumeration of next_action variants is slightly hard to scan.

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

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

For a single-parameter status tool the description is complete: it covers the states, the error path, the loop-driving next action, and the persistence side effect. An output schema exists, so return-value documentation is unnecessary and the extra detail is bonus.

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, project_id, with 0% schema description coverage. The description implies tenant scoping and mentions project_id in the submit_request example, but never clarifies the expected format (ID vs name) or how to obtain it, so it adds limited semantics beyond the self-evident 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: checking whether a new project has finished provisioning and is ready to build. It is clearly distinguishable from siblings like get_onboarding_status and project_status through the provisioning-stage framing.

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 prescribes behaviour per state: poll with poll_after_seconds while provisioning, do NOT poll while errored (fix the cause first), and call submit_request(project_id, text) once 'ready'. This is when-to-use guidance at the level of an agent loop, not just a hint.

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 saying little beyond readOnlyHint/idempotentHint being false, the description carries the burden and does so well: it enumerates the full next_action state machine, marks cancelled as terminal and failed as error-bearing, and discloses the extra fields (stage, plan_cycle, max_cycles) present for planned requests. That is materially more than the annotations supply.

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

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

Purpose is front-loaded in the first sentence and the async caveat follows immediately. The long next_action breakdown is dense but each branch earns its place by naming the consequential outcome; only the trailing 'stage, plan_cycle and max_cycles' sentence is marginally thin on what those mean.

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?

An output schema exists, so the tool did not need to explain returns, yet it usefully maps the key response fields to agent actions. Combined with the polling guidance and terminal-state disclosure, an agent has enough to call and interpret this correctly; only the input parameters remain unexplained.

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 0% for the two required parameters (project_id, thread_id), and the description says nothing about what identifies a thread or where project_id comes from. The field names it does mention (next_action, generated_roadmap_item_ids, intake_failure_reason) are response fields, not inputs, so the gap in input semantics is unaddressed.

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 ('Check what happened to a request') and immediately scopes it to the async intake flow, which distinguishes it from submit_request, refine_request, and answer_request. An agent can tell it apart from the sibling status tools (project_status, get_provisioning_status) without opening a schema.

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

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

Explains the polling context explicitly ('Intake is async (~5min cadence), so the status changes between calls') and routes each terminal/branching state to the correct follow-up: answer_questions -> answer_request, done -> generated_roadmap_item_ids, failed -> intake_failure_reason, approve_plan -> dashboard. It stops short of naming when to prefer this over get_provisioning_status or project_status, 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?

Annotations already flag destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description goes well beyond them: replay-guarded re-imports returning already_exists=True, in-place restoration of a soft-deleted row, restored queued work that can delete tasks, non-idempotency end to end, and loop being OFF with next_step naming get_billing(). This is unusually rich operational context for a write 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 intent sentence and the create_project contrast are front-loaded, then parameters are handled in labeled blocks, so it scans well despite its length. It is dense and occasionally repetitive (visibility and detection caveats restated), which keeps it short of a 5, but each paragraph carries real 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?

With an output schema present, return values need no explaining, and the description still covers the two outcome branches that matter (already_exists on replay, loop OFF with get_billing() routing, else get_provisioning_status). For a destructive, non-idempotent, open-world import with 6 params, 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 0%, so the description carries the full burden and does: repo_full_name format 'owner/repo' plus visibility rule, engine's enum values and default, project_kind's enum values with auto-detect/override semantics and the cases that block the dev lane, stack's language axis, and the conditional requirement on preview_command. Nothing material about the six parameters is left undocumented.

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

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

Opens with a specific verb and resource ('Connect an EXISTING GitHub repo as a Keelen project') and immediately disambiguates against the sibling create_project, stating this is for pre-existing repos while create_project scaffolds new ones. An agent can select it correctly without touching the schema.

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

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

Gives explicit when-to-use vs create_project, tells the agent to call list_github_repos() to verify visibility (and that non-visible repos 404), and names submit_request as the follow-up when no build_description is supplied. It also states the conditions that make project_kind and preview_command mandatory, which is exactly the routing guidance an agent needs.

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 by disclosing edge cases (synthetic `orphan:<project_id>` rows, null `roadmap_item_id` for task-only/synthetic rows), server-derived flags, and a critical invocation nuance — that `requeue_for_review` takes the row's task_id rather than its id. Annotations only assert readOnlyHint=false/idempotentHint=false; the description supplies the real operational context.

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

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

Front-loaded with a crisp purpose sentence, but the middle is a single dense block enumerating return fields and next_tool routing. Since an output schema exists, much of the return-field enumeration is arguably redundant, and the routing detail crowds the core message.

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 lookup-style tool with an output schema, it is more than complete on behavior and routing. The one clear hole is the undocumented required parameter, which leaves the agent without guidance on what `project_id` should be.

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

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

The schema has 0% description coverage and the single required `project_id` parameter is never explained, nor is its scope (does it imply workspace scoping?). The description never mentions the parameter at all, so it fails to compensate for the schema gap.

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 ('See what the work is stuck on... this returns each one') and explicitly distinguishes itself from the sibling `project_status` ('only COUNTS open escalations; this returns each one'). An agent can tell exactly what this returns versus its nearest alternative.

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

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

It clearly names the alternative (`project_status`) and the condition that separates them, and it routes each row type to a specific follow-up tool (`retry_blocked_task`, `rearm_roadmap_item`, `replan_task`, `resolve_escalation`). It stops short of stating when NOT to reach for this tool or prerequisites for calling 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?

Discloses a non-obvious side effect the annotations only partly imply: reading the list can mint a short-lived installation token, so it is not a pure read. This is consistent with readOnlyHint=false and adds real context. It then gives a complete, typed error taxonomy (409/429/502/503) mapping each provider failure to a named cause, which is far beyond what 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?

Front-loaded with purpose, then entries, then side effect, then error behavior — a logical progression with no filler. It runs a bit long in the error enumeration, but every clause carries distinct information rather than repeating structured fields.

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?

Complete for a zero-parameter, side-effecting list call: scope, downstream consumer, token-minting behavior, connection precondition, and a full failure taxonomy are all covered. An output schema exists, so the description is not obliged to detail return values, yet its field list is a useful pointer.

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

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

The tool takes zero parameters, so the baseline is 4. The description goes further by explaining the return fields (full_name, default_branch, private, language, pushed_at) and clarifying that full_name is the value import_project consumes, which adds semantics not present in the empty input schema.

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

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

States a specific verb (List) and resource (GitHub repos) plus the exact scope: repos the workspace's GitHub connection can see. It also names the consuming sibling, import_project, so an agent can immediately distinguish this from connect_github or import_project.

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 ties the tool to import_project (for import_project) and states the precondition that connect_github() must run first, backed by the concrete consequence (409 if GitHub isn't connected). This is exactly the when-to-use / prerequisite guidance the dimension asks for.

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

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

The description describes a plain enumeration ("List the projects in this workspace"), which is inherently a read-only, repeatable operation, yet the annotations declare readOnlyHint=false and idempotentHint=false. An agent reading the annotations would infer possible writes or non-repeatable side effects that the description never acknowledges or reconciles, so the two sources conflict.

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 with no filler; the verb and scope come first and the extra payload clause is the only addition. Nothing in it 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?

An output schema exists, so return values need not be explained, and with zero parameters there is little else an agent must know to invoke it. The remaining gap is the unresolved read-only question raised by the annotations, plus no mention of empty-workspace or pagination behavior.

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

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

The tool takes zero parameters and the schema description coverage is 100%, so there is nothing for the description to clarify. Baseline of 4 applies for a parameterless tool.

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 (list) and resource (projects), plus a scope qualifier ("in this workspace") and an add-on payload ("with what each one is building"). That is clear enough to separate it from create_project/delete_project/archive_project, but it never names or contrasts with the neighboring project-reading tools (project_status, project_digest), so it stops short of full sibling differentiation.

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

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

The scope phrase "in this workspace" implies when the tool is appropriate (enumerating all projects), but there is no explicit when-to-use or when-not-to-use guidance and no routing among the many project-related siblings. Usage is only inferable, which matches the minimum-viable level.

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 adds genuinely valuable domain behavior: the skip_reason precedence list, the meaning of electable, and the note that a skipped item ahead of yours does not delay it. But it frames the tool as a pure read ('See what is planned') while the annotations declare readOnlyHint=false and idempotentHint=false, i.e. a stateful operation; that unresolved mismatch undercuts the otherwise strong behavioral 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?

Front-loaded with the purpose in the first sentence, then focused detail on the interesting output fields. Every sentence earns its place, though the long parenthetical enum of skip_reason values is dense.

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?

An output schema exists, so return values needn't be described, yet the description still explains the key fields (electable, skip_reason, awaiting_clarification). The gaps are the undocumented status parameter and the ambiguity about side effects, so it is not quite a 5.

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 0% and neither parameter is explained in the text. 'Queued rows' faintly hints that status defaults to 'queued', but no allowed status values or project_id semantics are given, so the description does not compensate for the coverage gap.

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

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

States a clear verb+resource ('See what is planned for a project') and adds the distinctive ordering aspect ('and in what order'), so an agent knows this lists a project's roadmap plan. It does not explicitly contrast with related siblings such as reorder_roadmap or project_status, which keeps it from 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?

Usage is implied (view a project's planned items) and it usefully cross-references list_escalations for the awaiting_clarification case, giving a concrete routing pointer. However, there is no explicit when-to-use/when-not guidance and no named alternative for viewing versus reordering or checking project status.

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

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

Annotations set readOnlyHint=false and idempotentHint=false, and the description explains exactly why: it mints a single-use token, the returned login_url works once and expires in 15 minutes, and a repeat call mints a fresh one. This is rich behavioral disclosure well beyond what the annotations convey, with no contradiction.

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 key action and output (a one-click sign-in link) are front-loaded in the opening sentence, and the following sentences explain token mechanics. It is slightly longer than strictly needed for a zero-parameter tool, but every sentence adds real context rather than restating structured fields.

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 no-parameter tool with an output schema already present, the description is more than complete: it covers why the tool exists, token lifetime, single-use semantics, and repeat-call behavior. 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?

The tool takes zero parameters, which establishes the baseline of 4. The description correctly implies no input is required ('this server has already authenticated the workspace owner'), so there is nothing further for it to document.

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

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

The first sentence states a specific verb+resource: minting a one-click, pre-authenticated dashboard sign-in link for the owner. It is clearly distinguished from all read-oriented siblings like get_billing or project_status, and an agent knows exactly what the tool produces without opening the schema.

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

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

The description gives strong usage context — needed by the engine-connect step and any dashboard task such as billing or a project page — which tells the agent when a signed-in browser is required. It stops short of naming a sibling alternative or an explicit when-not condition, so it sits at a clear context with no exclusions.

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

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

The description is unusually rich about behavior beyond the annotations: feature-flag registration, live-disable refusal, tenant scoping with 404, and the mandatory steering fields. However, it opens with 'Read' while the annotations declare readOnlyHint=false and idempotentHint=false, which is an inconsistency between stated and structured behavior.

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

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

Front-loads the one-line purpose, then return shape, then availability constraints. It is longer than average but each sentence adds operational information; the steering-field sentence is dense but justified by non-obvious semantics.

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?

Although an output schema exists, the description still supplies the semantics an agent needs (next_action/next_tool contract, more_decisions, clamping window) plus the gating and scoping preconditions. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does for `since`: optional ISO-8601 timestamp with timezone, defaults to 24 hours ago, clamped to the last seven days. `project_id` is only indirectly covered via the tenant-scoping sentence, leaving one parameter thin.

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 ('Read a compact progress digest for one project') and enumerates the exact contents (delivery counts, five newest delivered items, activity count, holds, top open decision, more_decisions). An agent can distinguish this from the sibling project_status without opening 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?

It gives strong availability gating (off by default, registered only with KEELEN_PROGRESS_DIGEST_ENABLED, live disable refuses calls, tenant-scoped 404) but never says when to prefer this over project_status or list_escalations. The when-to-use is implied by the return contents rather than stated against alternatives.

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

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

The description carries real behavioral weight beyond the annotations: it explains that glm_peak_paused is an intentional cost gate rather than a fault, that it sets no pause columns, and that runs resume at glm_peak_resumes_at. It also reconciles the readOnlyHint=false annotation by disclosing that the ui_review block can mint a GitHub installation token and read a remote file, so the call is not a purely local read.

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

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

Front-loaded with purpose in the first line, then layered nuance. Dense but each paragraph addresses a distinct concern (status fields, roadmap distinction, GLM pause semantics, side effects). Slightly long, but no filler sentences.

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

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

Given an output schema exists, the enumerated return fields are somewhat redundant, but the interpretive guidance (glm_peak_paused not being a failure, the roadmap count distinction) and the side-effect warning make the definition complete for correct invocation. Only the parameter itself is under-described.

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

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

Only one parameter (project_id) with 0% schema description coverage, but the description clearly frames it as the project being inspected and the return fields tie back to it. No format, identifier style, or lookup detail is added, so it does not go beyond what the obvious field name already conveys.

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, scannable statement of the resource and its scope ('Check how a project is doing: what is in flight, what shipped, what is stuck'), then enumerates exactly what is returned. An agent can distinguish it from siblings like list_roadmap or project_digest without opening the schema.

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

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

Provides clear interpretive context on when to read which field (e.g. zero open_tasks does not mean an empty roadmap, use list_roadmap for queued items). It names a sibling and its role, but stops short of explicit when-to-use/when-not conditions relative to tools like project_digest or list_projects.

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 already flagging non-read-only, open-world and non-idempotent behavior, the description still adds real traits beyond them: a replay guard, verification of delivered prerequisites, exactly one bounded expand retry, id/dependency preservation, resolution of matching cards in a single transaction, and a bounded live GitHub check that can reach out even when nothing changes. It stops short of permissions, auth, or failure-mode disclosure.

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

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

The core action is front-loaded in the first sentence, and the following sentences each add operational detail. Backtick-heavy domain jargon adds density but little waste; the whole is appropriately sized for the operation's complexity.

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

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

An output schema exists, so return values need not be explained. For a single-parameter, transaction-scoped mutation the description covers preconditions, semantics, and external-call behavior adequately; only the id's source and error behavior are absent.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does: escalation_id is scoped to two escalation kinds, effectively an implicit enum beyond the bare string type. It does not say where to obtain the id, but it meaningfully compensates for the empty schema.

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

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

The description names a specific action (re-arm) on a specific resource (a roadmap item's same-item dependency) keyed by an escalation id, and elaborates the concrete steps (verify prerequisites, grant one expand retry, resolve cards). It is clear what the tool does, though it never names or contrasts a sibling such as cancel_roadmap_item or retry_blocked_task.

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 statement that escalation_id must be an expand_produced_nothing or roadmap_item_parked id implies when the tool applies, which is useful precondition context. However there is no explicit when-to-use rule, no exclusions, and no routing against alternatives, leaving the agent to infer the scenario.

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/readOnlyHint/openWorldHint, and the description layers on genuinely new behavior: the thread moves to refine_pending, refinement re-plans roadmap items, can edit or HARD-DELETE previously generated task rows, and there is a cap of five refinements per thread. This is exactly the kind of consequence detail 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-loads the intent then packs the constraints into a few tight sentences with no filler. The parenthetical about the machine patch-tasks endpoint is slightly tangential but still earns its place as a destructiveness explanation.

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?

Output schema exists so return values needn't be described, and the description covers the state transition, the destructive side effects and the call cap. The main gap is the meaning/scope of thread_id and project_id, which matters for a 3-required-parameter 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 description coverage is 0%, so the description carries the parameter burden. It does usefully constrain feedback_md (1..1979 chars), but says nothing about project_id or thread_id, leaving two of three required parameters undocumented in both schema and description.

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

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

States a concrete verb+resource ('say what is wrong... have it reworked') and names the artifact affected (request output, roadmap items). It is distinguishable from adjacent tools like answer_request, get_request_status and replan_task, though it never explicitly contrasts itself with 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 hard precondition ('Status must be "done"') and routes the agent to get_request_status to observe the revised items. It stops short of naming alternatives or when-not-to-use cases (e.g. vs. answer_request or replan_task), which keeps it out of 5 territory.

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 establish mutation-without-destruction (readOnly=false, destructive=false, idempotent=false), and the description adds real behavioral depth beyond them: horizon pins override ordered_ids position, unknown or de-queued ids are skipped, duplicates are rejected, and the returned shape is disclosed. It stops short of noting the non-idempotency implication or any permission/rate constraints, so 4 rather than 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?

Front-loaded one-line purpose followed by tightly packed semantics; nearly every sentence carries information the agent needs. The cadence/priority_int aside is slightly tangential but directly explains why order matters, so no serious bloat.

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

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

For a two-parameter mutation tool with an output schema present, the description covers ordering semantics, pin precedence, invalid-id handling, and validation rules — enough to call it correctly. Remaining gaps are minor (project_id meaning, failure/permission behavior) since the output schema already covers return shape.

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 0%, so the description must carry the load — and it does for the non-trivial parameter, explaining that `ordered_ids` is a front-to-back list where the first id becomes highest priority, with skip and duplicate-rejection rules. `project_id` is never explained in either schema or description, leaving one of two required params opaque.

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+outcome ('Change what gets built first') and names the exact resource and mechanism (`ordered_ids` ordering of queued roadmap-item ids). It also references the sibling that produces those ids (list_roadmap), letting an agent separate it from neighbors like cancel_roadmap_item or set_product_goal.

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

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

The description makes the usage context inferable ('use list_roadmap to obtain ids, then pass the desired order') and states ordering semantics, but never says explicitly when to reorder versus other roadmap-mutating siblings such as cancel_roadmap_item, rearm_roadmap_item, or set_product_goal, and offers no when-not guidance.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds real value beyond that: it discloses that lineage/prerequisites/dependents are transferred, the old task is cancelled with supersession provenance, and nothing is marked delivered. It leaves out the openWorldHint=true implication and any permission/idempotency caveat, but with annotations carrying the safety profile, this is a strong addition.

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

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

Two sentences front-loaded on the core action, with side effects following. No filler, no restated name/title. Every clause earns its place.

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

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

Output schema exists, so return values need not be explained, and the lifecycle effects (transfer, cancel, provenance) are described well. But for a destructive, open-world, 6-required-parameter mutation with zero schema description coverage, the description is incomplete — the required new content inputs are entirely 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 description coverage is 0% across 6 required parameters, so the description must compensate and does not. It never mentions title, body_md, decision_md, or acceptance_criteria — all required inputs an agent must supply — leaving the meaning and format of every parameter undocumented.

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+resource ('Replace an unretryable blocked task') and immediately differentiates from the close sibling by qualifying the task as 'unretryable' — which is exactly the condition separating this from retry_blocked_task. An agent can pick between the two without opening a schema.

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

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

The 'unretryable' qualifier strongly implies when to use this rather than retry_blocked_task, and the description names the replacement semantics. However, it never names retry_blocked_task as the alternative or states an explicit exclusion, so the routing is implied rather than declared.

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: states OAuth personal-connection requirement, refuses workspace keys, specifies resulting status (done, never delivered), that gates still apply, no retry and no budget reset, and the exact refusal shape (ok=false, review_requeue_refused, cause_code). This is unusually rich behavioral disclosure.

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

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

Front-loads the core action, then preconditions, then idempotency and refusal behavior. Information-dense with little waste, though the parameter enumeration is packed tightly into one long 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 destructive, gated mutation with four required params and an output schema, the description covers prerequisites, side effects, idempotency, and error contract. Nothing an agent needs to call it safely 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 0% schema coverage, the description fully compensates: task_id must not be an escalation id, expected_head_sha is the exact 40-character head SHA, reason is 1-2000 characters, and request_id is 1-128 chars from a stated charset. Each parameter gains meaning absent from 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 with scope: 'Return one blocked task's existing pull request to normal review.' An agent immediately grasps it acts on an existing PR, not a new run, which cleanly separates it from siblings like retry_blocked_task or replan_task.

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 preconditions for use (blocked task, own open PR, green/cleanly mergeable, verified DEV run) and rules out retry/budget-reset semantics. It doesn't explicitly name an alternative tool to use instead, so it stops short of a 5.

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

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

Even with annotations already declaring destructiveHint=true and idempotentHint=false, the description adds the underlying mechanics: the acknowledgement is replay-guarded but the call is not idempotent end-to-end because resuming a paused project can let queued refinement DELETE tasks. That is high-value behavioral context beyond the structured hints.

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 size is justified by the tool's complexity and each sentence contributes distinct information (precondition, audit note, resume side effect, blocked-task exclusion, idempotency caveat, ID format). It is dense and somewhat run-on, but not padded.

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

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

Given an output schema exists (so return values need not be described) plus annotations covering the safety profile, the description covers everything an agent needs: preconditions, the required audit field, side effects on pauses, the exclusion path with alternatives, idempotency behavior, and accepted ID formats.

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 0%, so the description must carry the parameter burden, and it does: decision_md is explained as a required short note appended to the escalation's detail_md as an audit trail, and escalation_id is documented as accepting either a real UUID or a synthetic `orphan:<project_id>`. Format/validation details are still thin, but this is strong compensation for a bare schema.

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

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

The description states a specific verb+resource – acknowledging a handled escalation – and distinguishes it from the sibling paths (retry_blocked_task, replan, close, supersede) that must be used for a blocked task's final block. The opening clause ('only when no blocked task becomes invisible') reads as a precondition rather than a plain statement of purpose, so it is slightly less immediately clear than it could be.

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 both the when-to-use condition (a handled ask) and an explicit when-not-to-use case with the correct alternatives named: a blocked task's final task_block/operator_action cannot be acknowledged; use retry, platform-policy resolution, replan, close, or supersede instead. This is exactly the routing an agent needs.

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?

Far exceeds what the annotations declare (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). It discloses that the decision becomes a new plan section, that lineage is requeued before resolution, the owner_decision_required error token, the audit of old/new specs, precise no-op conditions, and the explicit non-destructive guarantee that unrelated specs and criterion rows are untouched.

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 decision enum and then sections behavior by decision value, which fits the tool's complexity, and most sentences carry required semantics. A few clauses are overly nested (the static-sibling selector case), pushing length beyond what a caller needs on first read.

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

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

For a destructive-capable, multi-branch mutation tool with an output schema (so returns need no explanation), the description covers decision effects, prerequisites, error paths, and transactional guarantees thoroughly. The only gap is the semantics of escalation_id and decision_md, which the agent must guess.

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 0% schema description coverage the description must carry the load, and it does for the three complex parameters: it enumerates every decision value, constrains project_cap to 6..32, and fully specifies the selector_corrections nested shape and 10-entry limit. escalation_id and decision_md remain unexplained, so it is not fully complete.

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 (resolve) and resource (platform-policy conflict) and frames the outcome as a structured plan decision, which is more than a restatement of the name. It never explicitly distinguishes itself from the sibling resolve_escalation, so an agent must infer the boundary from the domain jargon.

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 conditional context for each decision value (when project_cap is required, which tasks/paths apply to correct_evidence_selector, owner-only prerequisites) and describes side effects. It stops short of stating when to pick this tool over resolve_escalation or requeue_for_review, leaving the primary routing question unanswered.

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 the server-side derivation of eligibility/tenant/task/status, the business-level replay guard ('an already-retried block is not retried again'), and the non-idempotency reason (credential-use state persistence). This adds material behavioral context that the structured fields only hint at.

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, then the parameter source, then the sibling distinction and the idempotency caveat. Slightly dense with backtick-heavy naming, but every sentence earns its place.

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

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

An output schema exists, so return values need not be described. With annotations covering safety and the description covering eligibility, replay behavior, and non-idempotency, the only missing piece is the meaning of decision_md, which is a required parameter.

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 0%, so the description must carry the load, and it documents escalation_id precisely (the task_block id from list_escalations). decision_md is left completely unexplained, which is a real gap for a required 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 specific verb and resource ('Grant one fresh attempt' on a 'recovery-budget task block') and explicitly distinguishes itself from the sibling resolve_escalation. An agent can tell exactly what this retries and why it is not the same as acknowledging an escalation.

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 that escalation_id comes from list_escalations and contrasts with resolve_escalation ('remains acknowledgement-only'), which gives clear routing for when to use which. It does not spell out preconditions like 'only call after fixing the underlying issue' in explicit when/when-not form, 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?

Goes well beyond the annotations: it explains that the retained build artifact is re-published, that a NEW Roblox version is minted pointing at the old build, and that behavior is fast/deterministic because nothing is rebuilt. It also enumerates failure semantics with retry guidance (404 unknown version, 422 no retained artifact, 409 Studio-open/rate-limit with 'a retry can succeed', 403/409 for invalid or unscoped Open Cloud key), which the destructiveHint/idempotentHint flags 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?

Front-loads the action in the first sentence, then layers behavior and error semantics. Slightly dense in the error-code enumeration, but each clause carries actionable 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?

Covers prerequisites, mechanism, idempotency implications (new version per call), and full failure taxonomy for a destructive, non-idempotent, open-world operation. Since an output schema exists, the return-value listing is a bonus rather than a necessity.

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 0%, so the description carries the burden. It defines `version_number` concretely (a previously-published version, discoverable in the Roblox Publishing card) and ties `project_id` to a `roblox_game` project. It still does not state the id format (UUID vs slug) or scoping for `project_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 ('Roll a Roblox project's place back to a previously-published version') with the scope ('previously-published') made explicit. No sibling tool covers version rollback, and the description preempts confusion with rebuild/deploy flows by saying it 'never rebuilds from source'.

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

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

Gives a clear operating context ('For a `roblox_game` project') and tells the agent where to source `version_number` (the web Roblox Publishing card lists published versions). It does not name an alternative tool or an explicit when-not-to-use condition, but no sibling offers a competing rollback capability.

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

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

Goes well beyond annotations: declares billability, a one-review-in-flight-per-project constraint, per-workspace rate limiting, and the refusal contract (ok: false plus a next step, no work started). It also flags the disclaimer_md output obligation and clarifies that no changes are made, which is consistent with destructiveHint=false; the readOnlyHint=false reflects that it starts a job.

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 in the first sentence and then layers constraints, prerequisites, and billing in short paragraphs. Every sentence carries operative information, though the prerequisite/refusal/rate-limit logistics could be tightened slightly.

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

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

Since an output schema exists, return values need not be explained, and the description covers what an agent needs to decide and invoke correctly: prerequisites, billable/rate-limit constraints, in-flight limits, refusal behavior, and the disclaimer obligation for the user.

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 0% for the single project_id parameter, so the description carries the burden; it only implies scope via 'for one project' without naming the parameter or its expected form. It does add the disclaimer_md field context, but that is an output/adjacent field rather than the request 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 specific verb and resource ('Start a ... security control gap review') and scopes it to one project. It clearly distinguishes itself from run_security_review and run_legal_exposure_review by framing the work as framework-context control observations (Cyber Essentials / CMMC L1-L2) rather than a generic security or legal review.

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 lists prerequisites (saved framework profile, eligible plan, allowlist) and states the negative scope ('does not determine framework standing'), which implies usage context. However, it never routes the agent explicitly against the close siblings run_security_review, run_legal_exposure_review, or get_control_gap_findings, so the when-vs-alternative decision 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?

Goes well beyond the annotations: billable, one review in flight per project, workspace-level rate limiting, offline checkout read, disclaimers that must reach the user, and the fact that every refusal returns ok:false with an actionable next_step and starts nothing. This is unusually rich behavioral disclosure and is consistent with readOnlyHint=false / destructiveHint=false (a spawned side-effecting job that nevertheless changes nothing).

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

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

Front-loaded with the core purpose and constraint sentences that each earn their place. Slightly sprawling prose ('Spawns a one-shot review machine that reads the checkout offline and maps what the code DOES onto...') that could be tightened, but no wasted or redundant sentences.

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?

An output schema exists, so return values need not be re-explained, and the description instead covers everything an agent needs before calling: prerequisites, refusal shape, billing, concurrency, rate limits, and the mandatory disclaimer field. Complete for a complex, gated, side-effecting review 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 description coverage is 0% and the single project_id parameter is never defined in the description. The text does supply useful context that the project carries a saved compliance profile and must be allowlisted, which is more than the bare schema, but it does not explain the parameter itself.

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

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

Specific verb and resource: 'Find where a codebase creates legal exposure (privacy, consent, data handling)' and it maps code behavior onto legal obligations. It clearly distinguishes itself from its reading sibling by pointing to get_legal_exposure_findings for consuming findings, so an agent can tell run vs. read apart without opening 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?

Explicit preconditions are enumerated: a saved compliance profile (409-shaped refusal without one), a plan carrying the feature, the project on the operator allowlist, and one review in flight per project. It also names get_legal_exposure_findings as the follow-up reader, leaving nothing to inference about when this tool applies.

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 (readOnlyHint=false, destructiveHint=false): discloses the scan taxonomy, that findings are human-triaged and never auto-applied, billable cost, concurrency limit (one in-flight per project), the operator allowlist gating that can return a message instead of running, and the paid-plan requirement. This is rich operational context an agent needs before invoking.

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 a strong one-line purpose, but the taxonomy enumeration is a lengthy parenthetical list that arguably belongs in docs. The parenthetical caveats (allowlist, paid plan) are useful but push the description toward overload.

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-param tool with an output schema, the description covers invocation preconditions (allowlist gating, paid plan, concurrency), side effects (billable, no auto-fix), and result routing (findings to Security review). Nothing essential is missing.

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

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

Schema coverage is 0% and the single parameter (project_id) is undocumented in both description and schema. However, the parameter is a self-evident id given the surrounding narrative. No additional syntax or format guidance is provided beyond the implied project scope.

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 ('Find security problems in a repository') and immediately scopes it as 'a deep, whole-codebase review,' which distinguishes it from the sibling review tools (run_control_gap_review, run_legal_exposure_review) by domain.

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?

Clearly conveys the usage context: one-shot audit whose findings go to human triage, no auto-fix, billable, one in-flight per project. It doesn't explicitly name the sibling review tools as alternatives, but the framing makes the use case unambiguous.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds non-obvious behavioral details: goal_md must be non-empty, the operation is tenant-scoped, and out-of-workspace projects 404. That is meaningful context beyond the structured data.

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

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

Two short, front-loaded paragraphs with no filler; the purpose leads and the constraints/return follow. Slight redundancy in restating the return shape when an output schema already exists, but overall tight.

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

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

For a two-parameter mutation with annotations and an output schema present, the description covers the key gaps: the non-empty constraint on the markdown, tenancy scoping, and the 404 failure mode. Return values are redundantly restated despite the output schema, but nothing essential to calling it 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 0%, so the description must carry parameter meaning. It documents goal_md as free-form markdown that must be non-empty, which is genuinely useful, but project_id is left entirely unexplained beyond its self-evident name (no format, id source, or lookup hint).

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

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

The description gives a specific verb ('Set') and resource ('Product Goal') and clarifies the semantic intent – the outcome to aim at right now so work is prioritised toward one thing. It does not explicitly name the sibling set_product_vision, which would have made the delineation between goal and vision unambiguous, so it falls 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?

Usage is implied by 'Set the outcome to aim at right now, so work is prioritised toward one thing,' which tells the agent this is for prioritisation focus. However, there is no explicit when-to-use vs when-not guidance and no mention of the adjacent set_product_vision / get_product_goal siblings that an agent might confuse this with.

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, idempotentHint=false and readOnlyHint=false, so the write semantics are covered structurally. The description usefully adds tenancy behavior (a project outside the caller's workspace returns 404), a validation constraint (vision_md must be non-empty), and the return shape — genuine context beyond the annotations. It stops short of saying whether an existing vision is overwritten, which is the key behavioral question for a destructive, non-idempotent setter.

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 purpose sentence followed by constraints and the return shape; every sentence carries information. Slightly informal and the return-shape line is arguably redundant given the output schema, but there is no 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?

Tenancy, validation, and return values are covered, and the output schema handles the response detail. The remaining gap is meaningful: for a tool annotated destructive and non-idempotent, the description never states whether it replaces an existing vision or how concurrent/duplicate calls behave.

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 0%, so the description must carry the burden and largely does: it defines `vision_md` as free-form markdown that must be non-empty, and describes `project_id` implicitly via the tenant-scoping/404 rule. Both parameters gain meaning not present in the bare string-typed schema.

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

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

The description states a clear resource (the product vision) and the effect of the call ('say what this product is for'), and the informal phrasing is backed by the explicit `vision_md` parameter. It does not, however, distinguish itself from the sibling `set_product_goal` or `get_product_vision`, which an agent must infer 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?

The clause 'so every run knows what it is building toward' implies the reason to set a vision, but there is no explicit when-to-use guidance, no prerequisite, and no statement of how this differs from `set_product_goal`. 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?

With only coarse hint flags available, the description carries real behavioral load: refusal semantics for lowering, the fact that both caps are enforced when keelen pushes and not in CI, the derived screenshot cap that moves in lockstep, and the alternate capture-run semantics when evidence_lifecycle is true (PRs split into capture batches, catalog retained regardless, lower not refused post-migration). It also states that repeated same-value calls change nothing. This is substantially more than the annotations 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-loaded with the core operation, and each paragraph covers a distinct regime (budget cap, catalog capture-run cap, idempotency). It is dense rather than padded, but the third paragraph is long and leans on unexplained internal jargon such as 'keelen pushes', 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?

Despite the tool's genuinely complex behavior, the description covers allowed values, reset semantics, refusal conditions, enforcement point, the two operating modes, and even the response fields (evidence_lifecycle, catalog, run_limits, project_status.ui_review) beyond what the output schema provides. 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 0%, so the description must compensate, and it does: scenario_cap is an integer from 6 through 32, null resets to the platform default of 12, the screenshot cap derives from it, and its meaning changes to a capture-run limit on catalog projects. The default/sentinel semantics are fully spelled out where the schema gives only an anyOf integer/null.

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

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

The first sentence names a specific verb (set/reset) and a precisely scoped resource (this web_app project's ui-review scenario budget). No sibling tool overlaps with this resource, so an agent can select it unambiguously 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 operating conditions: raising is always allowed, lowering is refused when the default branch already exceeds the smaller budget or the manifest cannot be read, and the cap is enforced on push rather than in CI. It even points to project_status.ui_review for live occupancy. It does not (and need not) compare against sibling tools, but there is no explicit 'use this instead of X' routing.

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

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false). It discloses the 15-minute code expiry, that a repeat signup resends, that responses are enumeration-safe/uniform, that it is rate-limited per IP and per email, and warns that a guessed address signs the user into another account. This is exactly the extra behavioral context annotations 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-loaded with the core purpose and the flow, and nearly every sentence earns its place given the destructive/login semantics. There is some redundancy between the 'explicitly confirmed' paragraph and the final warning about a guessed address, which keeps it from a 5.

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?

An output schema exists, so return-value explanation is not required, and the single param plus auth state, flow, prerequisites, expiration, and rate limits are all covered. Nothing an agent needs to invoke 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 0% for the single `email` parameter, so the description must carry the load — and it does: it explains that email is where the code is sent, that it must be explicitly provided and user-confirmed, and that it must not be inferred from client/git/ambient sources. It does not add format syntax, but semantic meaning is well covered.

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

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

The description opens with a specific verb+resource ('Create a Keelen account ... emails a 6-digit code') and immediately frames the dual role as login. It distinguishes itself from siblings by declaring it is one of only two unauthenticated tools and by naming verify_email as its flow partner, so an agent can separate it from the many authenticated tools without opening a schema.

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

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

Explicit when-to-use: 'UNAUTHENTICATED — the only tool besides verify_email that works before a bearer key is configured.' It lays out the exact call sequence (signup -> verify_email -> get_onboarding_status) and states the precondition that email must be user-confirmed before calling. Alternatives are named rather than 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?

With annotations already covering readOnly=false, destructive=true and openWorld=true, the description still adds auth requirements, failure semantics (cleanup failure leaves it active, busy subject refused), side effects (finalizes unfinished runtime iterations, holds legacy tasks, records owner/reason) and authority boundaries. The claim that 'a repeat returns the same receipt' sits in mild tension with idempotentHint=false, though it describes response behavior rather than effect-level idempotency.

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 sentence one and every subsequent sentence carries substantive information (preconditions, failure modes, authority limits) rather than filler. The second paragraph is a dense run-on sentence with heavy jargon ('binds the runtime', 'busy subject'), which costs some parsability.

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?

Return values need not be explained since an output schema exists, and annotations cover the safety profile. For a destructive mutation the description supplies preconditions, failure behavior, side effects and authority boundaries, leaving only the precise mechanics of what 'cleanup' performs and project_id's role underspecified.

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 0% - parameters carry only bare titles. The description partially compensates by explaining that the exact project iteration number binds the runtime and that the reason is recorded against the owner. project_id receives no explanation at all, so the compensation is incomplete for three undocumented required parameters.

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

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

The opening sentence gives a specific verb (stop), resource (one running iteration) and scope qualifier (after confirmed runtime cleanup). It is clearly distinct from siblings like close_task, replan_task or cancel_roadmap_item. However, it never names an alternative tool, so sibling differentiation must be inferred from domain knowledge rather than the text.

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?

Preconditions and exclusions are stated explicitly: a personal active workspace owner is required, and workspace keys/Portfolio delegation cannot stop compute, plus a busy subject is refused. This is real when-to-use guidance, but no alternative tool is named for the cases it excludes, 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 declare this is a non-read-only, non-idempotent, open-world write. The description adds value beyond them: a 16000-character limit on text and a disclosure of the return shape (thread_id, status, next_action, poll_after_seconds, next_step) plus the polling handoff to get_request_status. It doesn't note auth requirements or idempotency nuance, but the added operational detail is meaningful.

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 purpose, then the per-call constraint, then the return contract. Three short sentences, each carrying distinct information, with no filler. Slightly dense in the final return-value clause but well organized overall.

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 annotations covering the safety profile and an output schema present, the description is nearly complete: it covers purpose, the one-intent rule, the size limit, and the polling next step. The only gap is the semantics of workflow_profile, which nothing documents.

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 0%, so the description must compensate, and it only partly does. It clarifies the `text` constraint (<16000 chars) but leaves project_id and especially the optional workflow_profile entirely unexplained. The constraint on text is genuinely useful, but half the parameters remain opaque.

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 set: 'Ask for a change... a feature, a bug fix, or a new direction.' An agent immediately understands this is the entry point for submitting work. It references get_request_status as the follow-up, but doesn't explicitly differentiate itself from siblings like refine_request or answer_request.

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 real usage constraint ('Each call carries ONE feature or intent; a multi-feature ask belongs in separate requests'), which helps shape invocation. However, there is no explicit when-to-use vs. when-not-to-use against alternatives such as refine_request, so guidance is implied rather than fully specified.

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=true, idempotent=false) by disclosing that the call is UNAUTHENTICATED, that the code expires in 15 minutes, that only 5 attempts are allowed, that the api_key is revealed exactly ONCE, and that invalid/expired/consumed codes return a uniform error. This is rich, operationally critical context the annotations 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 core action and the reveal-once key, then layers auth state, validation constraints, the security warning, and the continuation workflow. Sentences are dense but none are redundant or restate the schema, so every line earns its place.

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

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

With an output schema present, return-value documentation is unnecessary, and the description covers the remaining gaps: auth status, expiry/attempt limits, security handling of the key, error behavior, and the next step in the flow. Nothing an agent needs to invoke 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 description coverage is 0%, so the description carries the full burden. It specifies that `code` is a 6-digit emailed code and that `email` + `code` must match a code issued by signup(email) within 15 minutes, which meaningfully constrains both parameters. Minor gap: no explicit format expectations for the email string (e.g., verified-address requirements), so a small amount of semantics is left implicit.

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 (Redeem) and resource (emailed 6-digit code) and names the exact output produced (reveal-once workspace API key). It distinguishes itself from sibling signup (which issues the code) and get_onboarding_status (which continues setup) without the agent needing to open 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 explicit prerequisites (email + code must match a code issued by signup(email) within the last 15 minutes, 5 attempts max), names the follow-up call get_onboarding_status() to continue setup, and tells the agent how to get a fresh code when one is invalid/expired/consumed. When-to-use and alternatives are fully covered.

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