Keelen

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false) by explaining that the answer is stored with the item, the card is resolved, the next planning run reads it, and a second answer to the same round is refused. It also documents the authorization model (active workspace owner's personal connection; workspace key or non-owner refused), paused-project behavior, and that refusals return ok=false with a refusal_code and store 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?

Purpose and trigger are front-loaded, and each subsequent sentence supplies distinct operational value (storage, idempotency, auth, pause state, refusal shape). It is dense but not padded, though the auth/refusal block 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?

An output schema exists, so return values need not be explained. Given the mutation semantics and owner-only auth, the description covers everything an agent needs: trigger source, answer length/uniqueness constraints, single-use behavior, permission requirements, paused-state handling, and refusal signaling.

Complex tools with many parameters or behaviors need more documentation. 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 burden. It adds the critical `answer_md` semantics (one answer covering every question, 1–4,000 characters) and implies `escalation_id` comes from the `list_escalations` row, but never names the field or its format explicitly, leaving a small 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 ('Answer an open planning question and release its roadmap item') and explicitly distinguishes itself from the sibling `resolve_escalation` ('does not answer a planning question'). The trigger row reason `expand_needs_clarification` makes it unambiguous which escalation type it handles.

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

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

Explicitly says when to use it (a `list_escalations` row with reason `expand_needs_clarification` whose `next_tool` names this tool) and when not to (resolve_escalation does not answer a planning question). It also gives the shape of a valid call: one answer covering all questions, 1–4,000 characters.

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 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?

Beyond the annotations, it discloses the state precondition (pending only), the no-op response for already-active rules, the 409 refusal for retired rules, and the audit-trail side effect of the caller's connection identity. The audit recording also explains why the operation is not marked idempotent even though a repeat call returns changed: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?

Four short sentences, front-loaded with the action and outcome, then inputs, then edge cases, then the audit note. No sentence is filler; the last one carries real 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 two-parameter mutation with annotations and an output schema, the description covers the state precondition, the error path, the return-flag semantics, and the side effect. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description has to carry parameter meaning. It names both inputs semantically (project id, rule id) and gives the provenance of rule_id, but supplies no format, source, or validation detail for project_id. Partial compensation for a low-coverage 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 (approve), a specific resource (one pending steering rule), and the outcome it produces ('so it reaches the iteration prompts'). This clearly separates it from sibling tools like retire_steering_rule and list_steering_rules without needing to open either schema.

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

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

Explicitly routes the agent to the sibling that supplies the identifier ('the rule `id` from list_steering_rules') and states the applicability conditions: only a pending rule changes, an active rule is a no-op returning changed:false, and a retired rule is refused with 409. That is when-to-use, when-not-to-use, and where to get inputs, all in one place.

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 declare destructive/openWorld/non-idempotent, and the description adds material context beyond them: engine choices require a matching connected credential, ci_runs_on labels without a registered runner are rejected rather than queued, and scaffolding failure triggers best-effort deletion of the just-created repo. That last sentence is a genuine disclosure of side effects an agent would not otherwise know.

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

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

Well front-loaded — purpose, then alternative, then mechanics — and most sentences earn their place given nine parameters and real behavioral caveats. It loses a point for ragged formatting (line breaks splitting sentences like "`engine` is\nOPTIONAL") and some mild restatement of the repo-creation outcome in the opening and third paragraphs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 an output schema existing, the description still flags the returned keys and the follow-up poll via get_request_status, plus the rare next_action="call_tool" submit_request arm. For a tool that creates external state, the failure/compensation path is covered, leaving nothing critical unstated.

Complex tools with many parameters or behaviors need more documentation. 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 full burden and largely discharges it: name is a short repo slug with no owner, project_kind is enumerated plus required, preview_command is conditional on web_app, framework is web_app-only with vite|next defaults, engine is enumerated with defaults and credential preconditions, org/private/ci_runs_on semantics all explained. Only minor gap is that build_description's content expectations are only lightly sketched.

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

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

Opens with a specific verb+resource+outcome ("creates a GitHub repo and begins work on it") and immediately names the sibling it is not (import_project) and the sibling for browsing (list_github_repos). An agent can distinguish this from every other create-ish tool in the sibling list 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 routing: "For a NEW repo. Given an existing repo, import_project(repo_full_name) is the right call" — with the consequence spelled out (a second empty repo beside it). It also states the mobile_app exclusion and points mobile/Expo cases at import_project, giving both when-to-use and when-not-to-use.

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?

Goes well beyond the annotations (destructive=true, idempotent=false) by disclosing that re-import is replay-guarded, that re-importing a soft-deleted repo RESTORES the row in place, that restored queued refinement can delete tasks, and that the call is not idempotent end to end. It also documents the uniform denial semantics (never reveals whether a guessed repo exists) and the plan-allowance fallback where the project is created with the loop OFF and next_step points to get_billing(). Nothing here contradicts the annotations.

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

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

The core purpose and routing sentence are correctly front-loaded, but the middle section balloons: the Expo config-file precedence list (app.config.ts, .mts, .cts, .mjs, .cjs, .js by filename presence, then app.config.json, then app.json) and the R2 roadmap caveats are implementation minutiae that crowd out decision-relevant content. Roughly half the text is a single niche case, which hurts scanning for the common path.

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

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

For a high-complexity, non-idempotent, destructive import tool, the definition covers authorization, error codes and retry, kind detection and override, credential prerequisites, restore semantics, and post-call next steps. An output schema exists, so the description is not obliged to explain the return payload, and what it does mention (already_exists=True) is a bonus rather than a gap.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: `repo_full_name` format ('owner/repo'), `engine`'s allowed values, default and credential prerequisite, `project_kind`'s full enum plus the cases where it is mandatory and the consequence of omitting it ('unknown' blocks the dev lane), `stack` axis, and the conditional requirement on `preview_command`. This is substantially more than the bare schema 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?

States a specific verb and resource ('Connect an EXISTING GitHub repo as a Keelen project') and immediately distinguishes it from the closest sibling: 'This is the counterpart of create_project: it is for a repo that already exists.' An agent can route between the two 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 about when to use and when not to (existing repo vs. scaffold), states the authorization precondition (same caller must have called list_github_repos within 10 minutes or hold a grant), and gives a concrete recovery path for the `repository_access_required` error: call list_github_repos again, then retry. It also names the sibling to use for post-import work (submit_request) and the follow-up polls.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false — they say nothing about content or routing — and the description fills that vacuum richly: synthetic orphan rows, server-derived task_retry_available, exact routing per escalation kind, and the legacy-ui-review vs. autonomy-ladder field difference. The one gap is that it never reconciles its read-oriented framing with the non-read-only, non-idempotent annotations.

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

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

The scoping distinction is correctly front-loaded, but the remainder is one dense paragraph that packs row fields, synthetic-row semantics, next_tool routing, and two mode-dependent behaviors into undifferentiated prose. It is informative but hard to scan, and multiple clauses could be split or trimmed.

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

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

Detailed enough that an agent knows what each row contains, what the synthetic rows mean, and which follow-up tool a row routes to, including the requeue_for_review task_id caveat. Since an output schema exists, the heavy return-field exposition is partly redundant, but the routing semantics it adds are not covered anywhere else.

Complex tools with many parameters or behaviors need more documentation. 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 required project_id, and the description only references it obliquely through the `orphan:<project_id>` synthetic row format; it never says how to obtain or scope it. With one parameter and no schema documentation, more was expected than what is given.

Input schemas describe structure but not intent. Descriptions should explain 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, specific framing: 'See what the work is stuck on and waiting for a human decision about,' which is unmistakably about listing escalations. It also explicitly contrasts with the closest sibling: '`project_status` only COUNTS open escalations; this returns each one' — an agent can distinguish the two 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 clear selection rule against project_status (counts vs. per-row detail) and names many downstream alternatives in the next_tool routing (retry_blocked_task, rearm_roadmap_item, requeue_for_review, answer_planning_question, resolve_escalation). It does not state exclusions such as when not to call this at all, so it falls short of the top mark.

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

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

The description discloses side effects that annotations cannot convey: reading the list can mint a short-lived GitHub installation token, so it is 'not a pure read,' which correctly explains the readOnlyHint=false and non-idempotent hints. It further details the 10-minute actor-bound proof that authorizes a later import, and maps failure modes to concrete status codes (409 with connect_github() for missing/suspended installation, revoked token, or permission denial; 429 rate limit; 502 other provider failure; 503 timeout).

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

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

Structure is front-loaded: purpose and caller scoping first, then the import linkage, then side effects, then error semantics. Every sentence earns its place, though the four-status error enumeration is dense and could be compressed to a table-like single clause without losing meaning.

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

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

For a zero-parameter tool with an output schema and partial annotations, the description covers everything an agent needs before calling: auth prerequisite, caller identity semantics, the side effect that explains the annotation profile, the proof artifact it produces, and all error outcomes. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing to disambiguate. The description instead spends its words on the shape of each returned entry (full_name, default_branch, private, language, pushed_at) and the significance of full_name as the import key, which is genuinely useful even though an output schema exists.

Input schemas describe structure but not intent. Descriptions should explain 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 and resource ('List the CALLER's own GitHub-visible repos') and immediately ties it to its downstream consumer, import_project. It also scopes the ambiguous notion of 'caller' by contrasting OAuth connectors from static workspace keys, so an agent can distinguish this from import_project or 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?

Usage context is strong: it is explicitly 'for import_project', and it states that a full_name is what import_project(repo_full_name) consumes, plus a hard prerequisite ('connect_github() is required first'). It stops short of an explicit when-not-to-use rule, but the workflow ordering (connect -> list -> import) 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?

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 only declare safety flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false) with no domain semantics, and the description adds real context: retired rules are omitted and helper flags like auto_approved indicate whether a human reviewed a rule. It does not contradict the annotations, though the odd readOnlyHint=false for a 'List' tool is left unaddressed.

Agents need to know what a tool does to the 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 one-line purpose is front-loaded and the follow-up paragraph is dense but each clause carries domain meaning (state values, origin values, auto_approved). The enumeration is long but not padded, since none of these value domains exist in the schema.

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

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

For a single-parameter read tool with an output schema, the description covers purpose, exclusions, and sibling routing well. It spends much of its text explaining returned fields, which the output schema likely already covers, but that redundancy is what supplies the missing value-domain semantics.

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

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

Schema coverage is 0% for the single required project_id, so the description must carry the load, but it says only 'this project's', which merely restates the parameter name. It offers no format, source, or expectation about which project identifier is accepted.

Input schemas describe structure but not intent. Descriptions should explain 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 ('List this project's ... steering rules') and scopes the result to active/pending while noting retired rules are excluded. It is clearly distinguishable from siblings like approve_steering_rule and retire_steering_rule. Minor ambiguity: it defines an 'expired' state while claiming only active and pending rules are listed, leaving unclear whether expired rules appear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 rather than stated: it explains what steering rules are and that approve_steering_rule/retire_steering_rule should be used with a rule's id, which sketches the view-then-act workflow. There is no explicit when-to-use statement, no exclusions, and no prerequisites (e.g. required permissions or project membership).

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 frames the operation as a pure read ("Read a compact progress digest", "advisory backlog is computed outside the activity window"), while annotations declare readOnlyHint=false and idempotentHint=false, implying possible state change. It supplies rich context on defaults, clamping and 404 behavior, but that direct read/write conflict is not reconcilable from the text, so the annotation contradiction dominates.

Agents need to know what a tool does to the 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 return payload, then parameters — a sensible order with no filler sentences. It is somewhat long because it enumerates output fields and steering contracts that an output schema may already carry, but each clause states a concrete contract, not 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?

Covers scope, error behavior (404 for out-of-workspace projects), parameter defaults/clamping, and the always-present steering fields, which is near-complete for a two-parameter digest whose output schema is already published. The one missing piece is any statement about whether calling it has side effects, which would have resolved the annotation conflict.

Complex tools with many parameters or behaviors need more documentation. 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, and it does: `since` is specified as an optional ISO-8601 timestamp with timezone, defaulting to 24 hours ago and clamped to seven days — far beyond the bare `anyOf[string, null]` schema. `project_id` gains semantics through the tenant-scoping/404 statement.

Input schemas describe structure but not intent. Descriptions should explain 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 ("Read a compact progress digest for one project") and parenthetically enumerates the digest's domains (delivery, activity, holds, next decision), which distinguishes it from project_status and open_dashboard. An agent can predict the payload shape before 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?

Usage context is implied ("one project", tenant-scoped) but the description never states when to prefer this over sibling tools like project_status, get_product_goal, or open_dashboard, nor any when-not condition. The only explicit routing guidance is inside the return value (`next_tool="list_escalations"`), not about when to call this tool itself.

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

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

Adds substantial context beyond the annotations: `glm_peak_paused` is an intentional cost gate and not a fault, `pass_rate` is not a delivery measure and degrades when `verify_errored_14d` dominates, `ui_review` is absent by default because the autonomy ladder owns that budget, and in legacy mode the call can mint a GitHub installation token so it is "not guaranteed to be a purely local read" — which also explains the non-read-only hint.

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

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

Front-loaded with a strong one-line summary and organized into topical paragraphs, which keeps it navigable. But it runs several hundred words and the "Returns lifecycle status, open task count, ... " sentence largely restates the output schema, so a meaningful share of the text is redundant given a schema already exists.

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

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

Field-level semantics are unusually thorough and an output schema exists, so return values are well covered. Gaps remain: no guidance on the required `project_id`, no error behavior, and no differentiation from `project_digest` or `get_product_goal`, which an agent choosing among status-reporting siblings would need.

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

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

The single parameter `project_id` has 0% schema description coverage, so the description carries the full burden — yet it never mentions the parameter, its format, or where to obtain an id (e.g. via list_projects). The prose is entirely about return fields, leaving the only input undocumented in both places.

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

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

Opens with a concrete verb+resource framing ("Check how a project is doing") and enumerates exactly what the payload covers, so the agent knows this is the aggregate status view rather than a row-level read. It never distinguishes itself from the similarly scoped `project_digest` sibling, which is the one remaining ambiguity about what this tool is for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 routing to alternatives in two places: `open_escalations` is a count and "read list_escalations for the rows", and `queued_roadmap_items` is expanded by `list_roadmap`. It never states when *not* to call this (e.g. when a per-project digest would suffice), so partial credit.

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 flag destructive=true and readOnlyHint=false, but the description adds real value beyond them: the default call changes nothing, removal is scoped to exactly ONE dependency, other dependencies are refused, and the card refreshes or auto-resolves afterward. It does not address idempotency (declared false) or any permission requirements.

Agents need to know what a tool does to the 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 dual list/remove behavior, then explains the why, then the mode switch, then the side effect. Every sentence carries information; nothing is repeated from the schema or title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 the description covers mode semantics, refusal behavior, and post-call card state. What an agent still can't determine is how to obtain the two optional IDs and what a refusal looks like at the call level.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does: escalation_id is constrained to a prerequisite_hold_stalled card, and the two optional IDs are explained as a coupled pair whose joint presence switches from read to destructive mode. No id format or origin hints (where to obtain predecessor_task_id) are given.

Input schemas describe structure but not intent. Descriptions should explain 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 ('list or remove a dependency') with a precise scope qualifier: the dependency points at a task cancelled without proof of delivery. It does not explicitly name which sibling to use instead (e.g. resolve_escalation, retry_blocked_task), so differentiation relies on the reader inferring it from the escalation-card 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?

Gives a clear when: a held prerequisite whose dependency points at a cancelled task can never start. Gives an explicit mode selector (no task_id/predecessor_task_id = list, both = remove) and an exclusion ('any other dependency is refused'). It lacks guidance on when to prefer this over resolving the escalation card outright.

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?

Despite annotations already marking this destructive and non-idempotent, the description adds substantial behavior detail beyond them: lineage preservation, transfer of prerequisites and downstream dependents, cancellation with supersession provenance, audit history retention, and that nothing is marked delivered. It also discloses validation limits that reject inputs without writes, the authenticated GitHub read required for carry_forward, and that the head SHA is server-resolved.

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

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

The description is front-loaded with the core action and effects, then moves to constraints and parameter semantics in a logical order. Paragraphs are dense but every sentence adds operational value (lineage, limits, strategy choice, authentication requirement) 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, multi-effect task-replacement operation with an output schema, the description covers what changes, what is preserved, what is rejected, and the critical workspace_strategy decision. Given the output schema exists, return-value detail is unnecessary, and nothing essential for correct invocation is missing.

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

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

With 0% schema description coverage, the description must compensate, and it does well for workspace_strategy (fresh_main vs carry_forward, required when undelivered implementation is identified) and recovery_source_pr_number (declared PR checked via authenticated GitHub read). It also specifies size limits for title, body_md, acceptance_criteria, and decision_md. However, project_id and task_id are not described, and decision_md semantics beyond its character limit remain unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 line gives a specific verb and object ('Replace an unretryable blocked task') and immediately distinguishes the scope from retry semantics via 'unretryable'. The follow-up sentences enumerate the concrete effects (fresh task under same lineage, transfer of prerequisites/dependents, cancellation with supersession provenance). An agent can tell this is not 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?

It clearly establishes the condition for use ('unretryable blocked task') and gives detailed when-to-use/when-not guidance for workspace_strategy, including that carry_forward is refused until the runner path is enabled. The main gap is that it never names the sibling retry_blocked_task as the alternative for retryable blocks, leaving that contrast implicit.

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

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

Goes well beyond the annotations: 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?

Beyond the annotations (destructive, non-idempotent, openWorld), the description discloses the real consequences: resuming a project_pause/orphan_pause clears the pause and lets queued refinement run, which can DELETE tasks. It also clarifies the partial idempotency boundary (acknowledgement replay-guarded, end-to-end call not idempotent), which is precisely the nuance the annotation flag 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 guard condition, then parameters, then alternatives, then safety consequences — a sensible ordering with no filler. It is dense and a few phrasings ('no blocked task becomes invisible') take a second read, but every clause carries information.

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

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

For a destructive, non-idempotent mutation with an output schema already covering return values, the description covers preconditions, parameter formats, unsafe side effects, and correct alternatives. An agent still has to infer exactly what 'acknowledge' changes about the escalation record beyond the appended note, but nothing needed 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 coverage is 0%, so the description carries the full burden and does: decision_md is defined as a required short why/how note appended to the escalation's detail_md as an audit trail, and escalation_id is documented as accepting either a real escalation UUID or a synthetic `orphan:<project_id>` form. That is substantially more than the bare schema provides.

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

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

The core action (acknowledge/resolve an escalation) is clear from the title plus body, and the description distinguishes this tool from siblings by naming the cases that belong to retry_blocked_task, answer_planning_question, and cancel_roadmap_item. The opening sentence is conditional phrasing rather than a plain statement of purpose, which slightly blunts first-read clarity.

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

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

It specifies exactly when the tool applies (handled asks), explicit exclusions (a blocked task's final task_block/operator_action, an open planning question), and the correct alternative tool for each exclusion. Prerequisite conditions are stated rather than 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?

Goes well beyond the annotations by disclosing the transaction shape ('records the decision, requeues the same task lineage and resolves the card in one transaction') and a precise list of side effects it does NOT cause (no budget, no waiver, no recovery rung, cannot correct a frozen evidence selector). It also states the failure mode — a fixed conflict with no changes — which an agent needs to interpret a refusal.

Agents need to know what a tool does to the 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 recovery action and the card precondition are front-loaded, followed by the effect/no-effect breakdown and the refusal rule. Dense with jargon but each sentence adds a distinct constraint; the registration-endpoints trailing clause is the one bit that doesn't help an agent choose or call the tool.

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

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

A mutation tool with an output schema, so return values needn't be explained, and annotations already cover idempotency and destructiveness; the description supplies the preconditions, atomicity, and refusal behavior. Only the exact format of decision_md and what the fixed conflict looks like are left unstated.

Complex tools with many parameters or behaviors need more documentation. 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 full burden, and it does add real meaning: escalation_id must be an *open* platform_policy_conflict card tied to the postprocessor writer, and decision_md is a recovery note recorded on the new plan section. It doesn't specify string format or length, but the value constraints are materially clarified.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Recover a task') and narrows it to a precise case: an open platform_policy_conflict card attributed to Keelen's postprocessor writer. That is enough to separate it from generic siblings like resolve_escalation or retry_blocked_task, though the domain jargon ('postprocessor writer', 'evidence selector') assumes insider knowledge.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 enumerates the when-not cases ('any other reason or origin — a ui-review-origin conflict, an internal receipt, an exhausted hold, or a budget or catalog signal — is refused'), which is strong negative guidance. It stops short of naming the sibling tool an agent should use instead for those refused cases.

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

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

Annotations already mark it destructive and non-idempotent, and the description goes well beyond that: rule text and history are preserved, retirement is logged in Loop Activity, an already-retired rule returns changed: false, running iterations keep their original prompt. This is exactly the extra context annotations cannot supply.

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

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

Front-loaded with the action and scope, then layered: prerequisites, edge case, irreversibility, concurrency note. Every sentence carries distinct information; nothing is redundant with the schema or annotations.

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

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

Output schema exists so return values need not be documented, yet the description still flags the changed: false case. For a destructive, irreversible mutation tool it covers prerequisites, side effects, logging, reversibility, and the restore path — nothing an agent needs 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 only does so partially: it gives provenance for rule_id (from list_steering_rules) but says nothing about expected format for project_id or rule_id. Baseline 3 for a low-coverage two-parameter schema is fair.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Retire one steering rule') plus the exact scope ('so no later iteration prompt carries it'), which separates it cleanly from approve_steering_rule and list_steering_rules. An agent knows what the operation does without opening the schema.

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

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

Explicitly says to pass the rule id from list_steering_rules, that it works for active or pending rules including auto-protected retro kaizen, and names the alternative path for reversal: 'There is no un-retire: to bring a convention back, submit it as a new Request.' When/when-not/alternative are all covered.

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

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

Goes well beyond the destructive/readOnly/idempotent annotations: all-or-nothing transaction on a foreign rule (404), one audit row per changed rule, changed:false for already-retired rules, no un-retire path, and running iterations keep their original prompt. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the core action, then dense facts each earning their place. Slightly long-winded in the middle 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?

Output schema exists so return values needn't be documented, yet the description still explains changed:false and the 404 failure mode. Combined with annotations and the transaction semantics, nothing an agent needs 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 must compensate: it names project_id, explains rule_ids come from list_steering_rules, and states the 1-100 cardinality limit. That covers both params meaningfully, though it doesn't specify id format.

Input schemas describe structure but not intent. Descriptions should explain 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 (retire) and resource (steering rules) plus bulk scope (several in one transaction), which cleanly distinguishes it from the singular sibling retire_steering_rule.

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

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

Tells the agent to source ids from list_steering_rules and that it covers both active and pending rules including protected retro kaizen, and references the single-rule behavior as the alternative. It doesn't explicitly say 'use retire_steering_rule for one rule', but the context makes the choice clear.

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

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

Goes 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?

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.