Keelen

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

Annotations indicate a non-read-only mutation (readOnlyHint=false). Description adds the state transition ('Flips the thread back to intake_pending') and the requirement to answer every question exactly once, which is useful beyond annotations. Could mention failure modes, but sufficient.

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

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

Two sentences plus a parameter spec, all high-value. Front-loaded with purpose and precondition, no wasted words.

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

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

Given output schema exists (return value not needed) and moderate complexity, the description covers purpose, precondition, parameter details, and post-condition. It is complete for an agent to invoke correctly.

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

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

Schema has 0% description coverage, so the description must carry the load. It fully explains the `answers` structure with idx source and character limits, and clarifies the 'every question exactly once' rule. project_id and thread_id are self-explanatory.

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

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

Description states a specific verb+resource: 'Answer a thread's clarifying questions' with a clear precondition (status must be awaiting_answers). It distinguishes from siblings like submit_request (new) and get_request_status (polling) by focusing on the answering action.

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

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

Provides explicit context: must be in awaiting_answers status, and instructs to poll get_request_status after. It implies when to use (when questions are pending) but lacks explicit when-not or alternatives, so not a full 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 already indicate destructive and idempotent hints. The description adds valuable details: it stops in-flight machines, flips status, keeps history, and is reversible. No contradiction with annotations.

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

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

The description is a bit lengthy but well-structured with clear clauses. It conveys multiple aspects without being redundant. Each sentence adds useful information, so it remains effective.

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

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

Covers what happens (stops machine, flips status), the reversibility, and its relationship to delete_project. It does not mention return values, but that's acceptable given the absence of an output schema. Overall, it is sufficiently complete for the tool's complexity.

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

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

The input schema has one parameter (project_id) with no description, so coverage is low. The description implies it refers to the project to archive, but does not explicitly explain the parameter's semantics or format. More detail would improve clarity.

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

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

The description clearly states the action (archive a project) and its effect (frees a project slot, reversible shelve). It distinguishes itself from delete_project by emphasizing reversibility, making the purpose unambiguous.

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

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

Explicitly advises 'Prefer this over delete_project unless you specifically want the project gone', providing clear when-to-use guidance. Also explains additional effects (stops in-flight machine, drops out of cap) that help decide when 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?

The description discloses multiple behavioral traits beyond the annotations: it drops the item from the expand queue, resolves open expand-lane escalations, is idempotent after cancellation, and returns a 409 conflict while actively being expanded. It also specifies the return payload, giving full transparency.

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

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

The description is structured with the purpose first, followed by usage, behavior, and return value. Each sentence adds distinct information without redundancy, and the length is appropriate for the tool's complexity.

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

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

The description covers purpose, usage, edge cases (idempotency, 409 conflict), and return value. With only two parameters and an output schema, this is sufficiently complete. The annotations provide safety context, and the description adds the necessary operational details.

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

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

The input schema lacks any parameter descriptions, so the description must compensate. It explains how to obtain item_id (via list_roadmap), but does not explain project_id. Given the low schema coverage, this is a partial gap. The parameter list is simple, so it is adequate but not comprehensive.

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

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

The description clearly states the verb 'Cancel / close' and the resource 'single roadmap item', and distinguishes itself by directing the user to get the id from list_roadmap. This makes the tool's purpose unambiguous relative to siblings.

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

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

The description explicitly states when to use the tool: for DELIVERED or duplicate items that keep re-parking, and explains the problem (recurring escalations). It also gives context about what cancelling does, effectively guiding the agent to choose this over alternatives like resolving escalations directly.

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 beyond annotations by disclosing side effects (reprices queue, affects reorder_roadmap), the 422 error on non-queued items, and the returned structure. Annotations show this is a mutation (readOnlyHint=false) but idempotent; the description adds context about the queue behavior and error handling.

Agents need to know what a tool does to the 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 tight and front-loaded, with the core action in the first sentence, followed by concise behavioral details. Every sentence earns its place—no redundancy or padding.

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

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

For a tool with a simple two-parameter schema and output schema, the description fully covers the necessary context: the rationale for using it, the domain constraint (queued only), the error behavior, and the return value shape. Nothing important 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 implicitly identifies item_id as the roadmap item, but does not explicitly elaborate on either parameter's purpose or relationship (e.g., project_id scoping). While the description's context helps a bit, it doesn't add meaning to the parameters themselves.

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

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

The description clearly identifies the action ('Clear a queued roadmap item's horizon pin') and the resource (roadmap item's horizon pin). It distinguishes itself from related tools by naming reorder_roadmap and cancel_roadmap_item, making its unique function explicit.

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

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

Provides explicit when-to-use: to unpin a stale pin that is clogging the queue, and when-not-to-use: on non-queued items (refuses with 422). It names an alternative (cancel_roadmap_item) for closing delivered items, giving clear usage boundaries.

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 behavior beyond annotations: the task is marked cancelled but keeps all history, the reason is recorded on the audit trail, superseded_by parameters record provenance, closing does not claim delivery on the default branch, and the operation is idempotent. It also explains the response count and the planning-capacity impact. The destructiveHint annotation is not contradicted; the description clarifies what 'destructive' means here.

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

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

The description is front-loaded with the core purpose and then organized into logical sections: usage triggers, behavior/requirements, error cases, response interpretation, and rationale. It is longer than minimal but each paragraph adds distinct and necessary information, with no wasted words.

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

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

Even though an output schema exists, the description explains the meaning of the echoed `open_tasks` count, how to interpret a non-decreasing count, error behavior, idempotency, and dependency implications. This is comprehensive coverage for a mutating tool with subtle side effects and edge cases.

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

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

Schema description coverage is 0%, so the description must compensate. It provides meaningful guidance for `reason` (required, one line, audit trail) and for when to use `superseded_by_pr_number` or `superseded_by_task_id`. While `project_id` and `task_id` are not explicitly explained, their names are self-evident, and the optional parameters receive the needed context.

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

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

The description states a specific verb+resource ('Close a task'), defines the target ('a duplicate, or work already shipped'), and makes clear the tool is for cancelling/obsoleting tasks rather than deleting or re-planning them. It distinguishes itself from siblings like cancel_roadmap_item and replan_task by focusing on task-level closure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('Use this when a task on the board is obsolete...') and provides concrete triggers such as 'already landed in another PR' or 'user changed direction'. It also describes refusal conditions (409 during a running iteration, 404 for other workspaces) and directs dependent tasks to 'deliver or re-plan those separately'.

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 readOnlyHint=false (action tool), openWorldHint=true (external side-effects), and idempotentHint=false. The description adds genuinely useful context beyond these: the returned install_url flow, that the user must complete approval in a browser, the 10-minute expiration, and the requirement to poll a separate tool for completion. No contradiction with annotations; the description enriches the behavioral picture appropriately.

Agents need to know what a tool does to the 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: purpose, then the browser flow + polling step, then expiry. Front-loaded with the key outcome. Every sentence earns its place with zero waste or redundancy.

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

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

For a 0-parameter auth-flow tool with an output schema present, the description is remarkably complete: it explains the return value (install_url), the complete user-side flow, the polling requirement tied to a sibling tool, and the expiry/retry behavior. There are no gaps in what an agent needs to know to correctly execute and follow up.

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

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

The tool has 0 parameters with an empty schema, so the baseline is 4. The description carries the full explanatory burden on the operational side — what the tool returns (install_url), how it's used, and when to retry — which compensates fully for the absence of parameters. Nothing more needed.

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

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

The description clearly states 'Get the link that connects a GitHub account, so work can reach real repos' — a specific verb (get) + resource (link connecting a GitHub account) + outcome (so work reaches repos). This clearly distinguishes it from all 33 sibling tools, none of which handle GitHub connection/auth.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 an explicit step-by-step workflow: send the install_url to the user, they pick an account/org and approve, then poll get_onboarding_status() until github_connected is true. It also names the alternative/next-step tool explicitly and states the 10-minute expiry with a retry instruction, covering when and how to use it.

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

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

The description goes well beyond the annotations by explaining the dispatch condition (only enabled, status='active' projects), the distinction between resetting a pause and flipping the scheduler, and the durable, independent behavior of process_now. It also discloses that the gate returns a typed reason and recovery step instead of a spawn promise, which is valuable runtime context.

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

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

The description is front-loaded with a one-sentence summary and then organized into a compact bullet list where each bullet covers one action's behavior. Every sentence adds meaningful information, and there is no redundant filler.

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

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

The description covers all four actions, their scheduler effects, the dispatch condition, and the distinctive gate behavior of process_now. It also states that the tool returns the resulting scheduler state, which, combined with the presence of an output schema, gives the agent sufficient context to invoke it correctly.

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

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

With 0% schema coverage, the description carries the parameter documentation burden. It fully explains the `action` parameter by listing the allowed values and their effects, which the schema does not. `project_id` is only implied by the overall phrasing, so a bit more explicit detail about it would push this to a 5.

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

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

The opening sentence states a clear verb/resource pairing: controlling a project's autonomous work via the scheduler. The enumerated action values (enable, disable, resume, process_now) remove any ambiguity about what the tool does, and it is clearly distinct from the surrounding sibling tools.

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

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

The description explains when each action is appropriate: enable/disable flips the scheduler enabled flag, resume clears a pause, and process_now forces an immediate intake batch. It does not explicitly name alternatives or exclusions, but the action semantics make the intended usage 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?

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description goes far beyond these by disclosing auth mechanics (repo created on a workspace member's token with repo-create OAuth access, no specific caller user), the error branch when no member can create in org, the CI-label rejection rationale (GitHub queues forever instead of failing), and the rare arm where next_action='call_tool' with next_tool='submit_request'. This is rich, annotation-independent behavioral context.

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

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

The description is long, but the information density justifies it given 9 undocumented parameters. Purpose and usage guidance are front-loaded in the first paragraph; parameters, edge cases, and return flow follow in logical order. The minor awkward line break around '`engine` is OPTIONAL' is cosmetic. Docked slightly for length despite every sentence earning its place.

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

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

For a high-complexity tool (9 params, 3 required, auth edge cases), nothing is missing: purpose, when/when-not, all parameter semantics, credential prerequisites, error paths, and the actionable follow-up flow (poll get_request_status with the returned thread_id). The output schema covers return structure, and the description explains what to DO with it — complete and actionable.

Complex tools with many parameters or behaviors need more documentation. 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 entire burden — and it delivers for all 9 parameters: name ('concise GitHub short repo slug (no owner)'), project_kind (full enum list), preview_command (conditional requirement), engine (enum + credential dependency), org (placement effect), private (default True), ci_runs_on (examples + failure semantics), framework (enum + rails it selects). Even build_description is contextualized as the first Roadmap Request. Fully 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?

Opens with a specific verb ('Start building something new: creates a GitHub repo and begins work on it') naming the resource and the orchestration side-effect (submitting a Roadmap Request). It explicitly differentiates from import_project ('If they already have a repo, use import_project...'). Purpose is unmistakable and distinguishes cleanly from siblings.

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

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

States the exclusive condition explicitly — 'Use this ONLY when the user wants a NEW repo scaffolded' — and names both the alternative tool (import_project with its argument) and the browsing helper (list_github_repos). There are no gaps: an agent knows exactly when to pick this tool versus its siblings.

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

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

Annotations already declare destructive=true and idempotent=true, but the description goes well beyond: it specifies the 'soft-delete' nature (row retained for audit), that it stops in-flight machines, and that there's no in-tool restore. It also states the scope restriction (owner-scoped, 404 if not in workspace). This adds substantial behavioral context without any contradiction to annotations.

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

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

The description is well-structured: a punchy one-liner summary, then a detailed explanation of side effects and caveats. Every sentence adds value (effects, restore nuance, idempotency, scoping), with no fluff or repetition. It's efficient and front-loaded.

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

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

For a destructive action with side effects, the description covers all critical aspects: the action itself, what gets stopped, how it affects project listing and cap, idempotency, scope, and the lack of restore path. With an output schema present and clear annotations, this is fully sufficient for an agent to use the tool correctly.

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

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

With zero schema coverage, the description needed to explain the project_id parameter, but the parameter name is self-explanatory. The description provides context on how the parameter's value is used (the project that gets deleted, and its scope semantics), which adds meaning beyond the bare schema. It doesn't explicitly restate that project_id is the identifier, but the surrounding text makes it implicit, so a small deduction is warranted.

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

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

The description opens with a specific verb and resource ('Soft-delete a project') and immediately contrasts with the sibling 'archive_project' by calling itself 'the harder option.' It clearly states the action and distinguishes it from alternatives, meeting the highest bar for purpose 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 explicitly names an alternative ('unlike `archive_project`') and explains when to use this over that — when you want to free a slot and permanently remove from active use with no restore. It also describes the exact consequences (stops machine, disappears from list, drops from cap) and notes the ownership scope and 404 behavior, giving the agent full context for decision-making.

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 goes well beyond annotations by explaining the Stripe checkout flow, the webhook that flips workspace to active, that compute unlocks automatically without agent action, and that past_due states return no checkout. It also explains the consequence of creating a new checkout for past_due (would create a second subscription). This is rich behavioral disclosure, and annotations (readOnlyHint false, openWorldHint true) don't contradict.

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

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

The description is front-loaded with the core purpose and then provides detailed behavior. All sentences contribute to understanding: it explains the plan values, the checkout behavior, the webhook handling, and the past_due exception. While somewhat long, the length is justified by the complexity of the tool's behavior. No redundant or vague statements.

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

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

The description explains the full flow: when checkout_url is returned, what to do with it ('send it to the user'), how payment completion works (webhook auto-unlock), edge cases (past_due, open-signup unpaid, churned, converting from free/trial), and it cautions against creating a duplicate subscription. Since an output schema exists (though not shown), not explaining return values is acceptable. The description is complete for an AI agent to understand when and how to invoke this tool.

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

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

The only parameter 'plan' is documented in the description with the allowed values ('starter', 'pro', 'agency') and default ('starter'), which the schema lacks (0% coverage). This adds semantic meaning beyond the schema. It could have been slightly clearer about the effect of plan choice on checkout, but the allowed values and default are sufficient.

Input schemas describe structure but not intent. Descriptions should explain 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 'Billing status + a Stripe checkout link when a NEW subscription is needed', clearly stating the tool retrieves billing status and returns a checkout URL only in new-subscription scenarios. It explicitly distinguishes from sibling tools (which are mostly project management) and specifies the resource (billing) and action (get). The mention of 'NEW subscription' narrows the scope, making it unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it says the tool should be used when there is no live subscription and a checkout link is needed, and explicitly warns that for past_due workspaces one should not use this tool (follow next_step for card update instead). It also details the edge case of converting from free/trial, which helps the agent decide when to invoke 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?

Beyond the annotations, the description adds meaningful behavior: results are grouped by evidence class with no total or overall outcome, empty groups do not prove a control exists, disclaimer_md must reach the user, and the tool has no compute quota. These are non-obvious traits that help an agent reason about the tool's output.

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

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

The description is front-loaded with the core purpose, then adds only high-value semantic and operational details. Every sentence adds useful information, and there is no filler or repetition of annotations.

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

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

Given the output schema is present, the description covers the remaining contextual needs: grouping behavior, lack of totals, meaning of empty groups, include_all semantics, limit behavior, and availability after the trigger closes. The tool is sufficiently well-defined for an agent to invoke it correctly.

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

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

Schema coverage is 0%, but the description compensates by explaining limit defaults and max, and by clarifying that include_all includes resolved, dismissed, and out-of-scope records. Project_id is implied by the mention of a project, but its exact source or format is not explicitly described.

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

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

The description opens with a specific verb and resource: Read a project's security-control observations and review boundaries. It clearly distinguishes this read tool from the sibling run_control_gap_review, which triggers a review rather than reading existing findings.

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

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

The description gives clear usage context: it is read-only, remains available after the review trigger closes, and should be interpreted with attention to not_determinable and outside_review_scope records. It does not explicitly name an alternative tool or state when not to use it, but the intended context is still 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?

Annotations already declare read-only, idempotent, non-destructive. Description adds that there is no compute, no rate limit, and it works even if the trigger is closed. It also clarifies `exposure_order` is an ORDER, not a score, and warns against interpreting it as a grade/percentage—valuable behavioral nuance beyond the annotations.

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

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

Description is front-loaded with the main purpose, then explains key semantics, parameter behavior, and operational notes. It's a bit long but every sentence adds value; no fluff. Well structured with clear separation of output, interpretation, and parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 adds essential semantic details like `exposure_order` being an order not a score, the meaning of `counsel_reviewed`, and the importance of `not_determinable`. It explains edge cases (works while trigger closed) and default behavior. Complete enough for an agent to use 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 has only types/defaults for limit and include_all; description adds meaning: limit defaults to 25 and max 100, include_all adds resolved/dismissed/out-of-scope rows. `project_id` is self-explanatory. This adds value beyond schema, though project_id is not explicitly described (but it's obvious). Coverage is good.

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

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

Description clearly states 'Read a project's legal exposure findings, worst exposure first.' This is a specific verb (read) + resource (legal exposure findings) + ordering (worst first), and distinguishes from sibling run_legal_exposure_review (which generates findings) and get_legal_exposure_findings (this is the getter). The purpose is unambiguous.

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

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

Provides actionable guidance: read `not_determinable` before summarizing, and ensure `disclaimer_md` reaches the user. It also explains `include_all` semantics (adds resolved, dismissed, out-of-scope) and notes it works while the trigger is closed. However, it does not explicitly contrast with run_legal_exposure_review or other siblings, though the read-only nature is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: the need to poll repeatedly, the meaning of `next_action` and `next_action_detail` deprecation, a security warning about credentials, and the `usage` block for capacity awareness. No contradictions with annotations.

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

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

The description is front-loaded with a one-line summary, then uses bullet-like lines for steps. Every sentence earns its place: security instructions, deprecation notice, polling behavior, and usage block. It is appropriately detailed for the complexity of the onboarding flow without unnecessary fluff.

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

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

Despite no parameters, the tool has a complex output schema and workflow. The description fully covers return fields, the `next_action` state machine, step-specific actions, deprecation, security, and the usage counters. It is complete enough for an agent to use the tool correctly without further documentation.

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

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

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates richly by explaining the output structure and how to interpret `next_action`, `next_tool`, and the deprecated field, far exceeding the baseline for a zero-parameter 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?

The description opens with a clear, specific statement: 'Check what is set up so far and what to do next to get building.' It names the exact resources (engine_connected, github_connected, project_count, payment_status) and the `next_action` flow, distinguishing it clearly from sibling tools like get_provisioning_status or project_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?

Provides explicit step-by-step usage: engine step (send dashboard /login link, never ask for credentials), github step (call connect_github), project step (create_project or import_project), launch step (poll get_provisioning_status). It also states polling is the agent's responsibility ('Re-checking is YOUR job'), giving clear when-to-use and alternative-tool 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?

Beyond the annotations, the description reveals crucial behaviors: the setter's destructive replace semantics, the return shape, the None sentinel for no goal set, and the tenant-scoped 404 for inaccessible projects. These details materially affect how an agent plans its calls.

Agents need to know what a tool does to the 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 organized into three focused parts: core purpose, critical warning about the setter, and return/error contract. It is compact, front-loaded, and every sentence adds usable 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?

The description fully covers the read behavior, the edge case of no goal set, the tenant error, and the dangerous interaction with the sibling setter. Combined with the output schema and annotations, an agent has everything it needs to invoke and interpret this tool correctly.

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

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

With schema description coverage at 0%, the description compensates by clarifying the role of project_id: it identies the project being read, and the tenant-scoping note explains a key failure mode for that parameter. For a single-parameter tool this is sufficient to resolve ambiguity.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Read a project's current product goal' with a clarifying parenthetical about the outcome work. It also names the sibling set_product_goal, immediately distinguishing the read operation from the write operation.

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

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

The description gives an explicit precondition for using the sibling tool: 'READ THIS BEFORE YOU CALL set_product_goal' explains that the setter replaces the whole document. It then walks through the correct sequence for editing a goal, which tells the agent exactly when to use this read tool as a first step.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations: exact return shape, `None` when no vision exists, tenant scoping, and the 404 behavior for projects outside the caller's workspace. No contradiction with 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?

Every sentence earns its place: it states the operation, warns about the setter's destructive replacement behavior, provides the safe usage pattern, documents the return value, and notes tenant scoping. The warning is front-loaded and clearly separated, making the most important operational guidance prominent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a single parameter, an output schema, and annotations covering safety, the description fully covers what an agent needs to call this tool correctly. It even includes the non-obvious 404 behavior and the None case, making the tool's contract complete.

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

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

Schema coverage is 0%, so the description carries the burden for parameter meaning. It clarifies that `project_id` is tenant-scoped and that out-of-workspace projects 404, adding semantic context beyond the bare parameter name. For a single obvious string parameter this is sufficient, though a bit more explicit format detail would be needed for a higher score.

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

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

The description states a specific verb ('Read') and resource ('a project's current product vision'), and clarifies what product vision means ('what the product is for'). It is clearly differentiated from the sibling `set_product_vision` and from `get_product_goal` by naming the exact resource.

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

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

The description explicitly instructs reading before calling `set_product_vision`, explaining why (the setter replaces rather than appends) and how to add a line (read, edit, set full result back). This gives the agent concrete when-to-use and how-to-sequence 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 read-only, idempotent, non-destructive behavior, and the description adds substantial context: return shape (overall, 7-stage checklist, error_kind), next_action semantics, ~10s poll interval, onboarding completion side effect, and tenant-scoped 404 behavior. This goes well beyond the structured annotations.

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

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

The description is compact yet information-dense, front-loaded with the core purpose, then enumerating return fields, polling behavior, and scoping in a logical flow. Every sentence adds value without redundancy.

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

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

Despite having only one parameter and no schema description, the description fully covers the tool's contract: what it returns, how to interpret next_action, when to poll, what happens on completion, and authentication/tenancy constraints. The presence of an output schema further reduces the need to describe return values in detail.

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

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

The schema only provides project_id as a required string with no description. The tool description compensates by explaining that the project must belong to the caller's workspace and will 404 otherwise, adding meaning beyond the bare schema. It doesn't specify how to obtain or format project_id, but the parameter is simple and self-descriptive.

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

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

The description uses a specific verb ('Check') and clearly identifies the resource ('a new project') and the condition of interest ('finished setting up and is ready to build'). It also differentiates itself from sibling status tools like get_onboarding_status and project_status by focusing on the provisioning pipeline.

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

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

The description provides clear polling context: wait with poll_after_seconds while provisioning/errored, and when ready, 'steer the loop with submit_request(project_id, text).' It doesn't explicitly exclude alternative tools, but it gives enough actionable guidance for when to invoke and what to do next.

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 readOnlyHint/idempotentHint annotations, the description adds meaningful behavioral detail: the ~5min async cadence, the meaning of each next_action state, terminal vs. processing states, and where to find failure reasons or generated roadmap items. This is rich, non-redundant transparency.

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

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

The description is compact and front-loaded with the main purpose, then efficiently presents the async polling behavior and the next_action state machine. Every sentence adds operational value, and the formatting makes the state values easy to parse.

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

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

Given the output schema exists, the description doesn't need to explain return values, and it still covers the important runtime behavior: async cadence, polling, state transitions, and downstream actions. This is complete for a status-check tool with strong annotations and an output schema.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter meaning, but it does not explain project_id or thread_id beyond the implicit 'a request'. The parameter names are somewhat self-explanatory, but the description adds no explicit guidance on how they relate to the request being checked.

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

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

The description uses a specific verb ('Check what happened') and clearly identifies the resource ('a request') plus the additional capability of reading questions the request asked. This distinguishes it from siblings like submit_request, answer_request, and refine_request, which perform different request lifecycle actions.

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

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

The description gives clear usage context: intake is async, so the agent should poll periodically, and it explains how to branch on next_action values, including explicitly calling answer_request when questions need answers. It does not explicitly state when not to use this tool, but the polling and branching guidance is strong.

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 states that re-importing is idempotent ('Re-importing the same repo is idempotent...'), but the annotation declares `idempotentHint: false`. This is a direct contradiction. According to the rubric, any contradiction earns a score of 1 regardless of other disclosed behaviors.

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

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

The description is long (~300 words) but every sentence earns its place given the tool's complexity. It is front-loaded with the core purpose, then structured logically by parameter, with edge cases and next steps clearly separated in paragraphs. There is no fluff or repetition; the density is justified by the 6 parameters and numerous conditional behaviors.

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

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

The description is comprehensive for this complex tool. It covers idempotency (though contradicted), plan-allowance behavior, monorepo handling, detection pitfalls, parameter override authority, and post-call follow-ups. It also names the related tools to use in different flows. Since an output schema exists, the omission of return-value details is acceptable. 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?

With schema description coverage at 0%, the description carries full responsibility for parameter documentation. It thoroughly explains each parameter: `repo_full_name` format and visibility requirements, `engine` options and credential prerequisites, `build_description` purpose and recommendation, `project_kind` values, monorepo detection caveats, `stack` usage, and `preview_command` requirements for web_app. This goes far beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Connect an EXISTING GitHub repo as a Keelen project.' It explicitly frames it as the counterpart to create_project and distinguishes the two use cases. This is a specific verb+resource with clear differentiation from its sibling.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'use THIS tool when the user already has a repo, and create_project only to scaffold a brand-new one.' It also references related tools like list_github_repos, submit_request, get_billing, and get_provisioning_status, explaining the expected next steps in various scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds meaningful behavior beyond those: synthetic orphan rows for forever-paused projects, a server-derived task_retry_available flag, and exact next_tool routing per escalation kind. These are non-obvious behaviors that an agent could not infer from the schema alone.

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

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

The description is front-loaded with the core purpose and then packs detailed behavioral information into a compact block. Every sentence contributes useful information, including the project_status contrast and next_tool routing. It is slightly dense but appropriately sized for the complexity of 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?

Given that an output schema exists and the tool is a read-only list operation with one parameter, the description covers the important behavioral nuances: synthetic orphan rows, retry flag, and next_tool routing. The only notable gap is the lack of explicit documentation for the project_id parameter, but overall the agent has enough context to select and invoke the tool correctly.

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

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

The input schema has a single required project_id string with no description, and schema description coverage is 0%. The description mentions project_id only in the context of a synthetic 'orphan:<project_id>' row, but never explicitly explains that the parameter selects which project's escalations to list. The meaning is inferable but not directly stated, which is a meaningful gap for a schema with zero parameter documentation.

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

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

The description opens with a specific verb and resource: 'See what the work is stuck on' and 'list_escalations' returns each escalation. It clearly distinguishes itself from project_status by contrasting 'only COUNTS open escalations' with 'returns each one with its kind, reason, detail_md, recommended_action...' This gives an agent a precise sense of what the tool produces and how it differs from a sibling.

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

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

The description explicitly contrasts with project_status, telling the agent when to use this tool for detailed escalations instead of a count. It also names follow-up tools via the next_tool mapping, which gives helpful routing context. However, it does not explicitly state when not to call this tool or what preconditions (e.g., project existence) apply.

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 as a safe, read-only, idempotent operation. The description adds significant behavioral details: the return fields (full_name, default_branch, private, language, pushed_at), the 409 error condition when GitHub isn't connected, and the recommended action to resolve it. This goes well beyond the annotations.

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

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

Three sentences, front-loaded with the action and purpose, followed by compact, high-value details about the response fields and error handling. No unnecessary words.

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

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

For a simple list operation with no parameters and an output schema, the description covers the essentials: what the tool returns, how to use it, and what to do on failure. It's complete for an agent to use it correctly.

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

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

There are zero parameters, so the baseline is 4. The description explains how to use the output (pass full_name to import_project), which adds helpful context for consumers of the returned data.

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

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

The description clearly states the tool lists repos visible to the workspace's GitHub connection, with a specific purpose ('for import_project'). It distinguishes itself from siblings like import_project and connect_github by defining its exact scope and output fields.

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

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

The description provides clear usage context: it's for listing repos to be used with import_project, and it instructs to call connect_github() if a 409 is returned. However, it doesn't explicitly state alternatives or when not to use this tool, though the context makes it fairly obvious.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that the response includes a building description for each project, providing behavioral context about the output 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?

Single sentence, front-loaded with action and resource, no filler. Effectively communicates scope and output without wasted words.

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

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

For a simple 0-param list tool with an output schema and strong annotations, the description is sufficient. It conveys what the list contains and adds useful context about project descriptions, leaving no significant gaps.

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

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

Tool has zero parameters, so schema coverage is complete. The description clarifies the workspace scope, which explains why no parameters are needed; baseline for 0 params is 4.

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

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

Description uses specific verb 'List' and resource 'projects in this workspace', and adds 'with what each one is building' to convey output content. This distinguishes it from sibling tools like list_roadmap, which lists roadmap items.

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

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

Description implies usage for viewing workspace projects but does not explicitly state when to use it over sibling tools like list_roadmap or project_status. No exclusions or alternatives are mentioned.

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

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

Annotations already cover read-only, idempotent, non-destructive. The description goes well beyond annotations by disclosing electable and skip_reason behavior, the full list of skip reasons, and the reassurance that a skipped preceding item does not delay yours. This is significant, non-obvious context.

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

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

The description is tightly composed: one sentence for the primary purpose, then a short paragraph for the one high-value edge case. The pipe-separated list of skip reasons is dense but organized and 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-value structure need not be described. The description covers the core purpose and the subtle queued-row behavior. Minor gaps remain: 'expand picker' is not explained, and status parameter values beyond 'queued' are unspecified, but overall it is quite complete for a read-only list 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 description provides almost no parameter semantics. It only hints at 'queued' through the phrase 'Queued rows' and the schema default. Allowed status values and the exact role of project_id are left to inference, so the description does not compensate for the missing schema descriptions.

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

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

States a clear verb and resource: 'See what is planned for a project and in what order.' This distinguishes it from mutating siblings like cancel_roadmap_item or reorder_roadmap, though it does not explicitly name an alternative or draw the distinction.

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

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

Implied usage is clear: call this when you want the planned roadmap for a project. The skipped-row explaination gives useful context about what you will see, but no explicit when-to-use/when-not-to-use statements or alternatie tool mentions are present.

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 important behavioral traits beyond the annotations: the token is single-use, expires in 15 minutes, bypasses email/password authentication, requires a pre-authenticated server context, and returns a deep link that lands the user at the proper onboarding location. This fully compensates for the sparse annotation hints.

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

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

Although the description is several sentences long, each sentence earns its place. The first sentence states the main purpose, and subsequent sentences provide needed context on when to use it, how the token works, the expiry, and how the result is consumed. No fluff or repetition 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?

For a tool with no parameters, the description is exceptionally thorough: it explains the prerequisite (already authenticated owner), the behavior (single-use token, 15-minute expiry), the output (`/login?token=...`), when to use it, and how the user should receive it. This covers all practical usage scenarios despite minimal structured schema/annotation data.

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

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

There are zero parameters, so the input schema is trivially complete and the description needs no parameter clarification. The description adds meaning by explaining the output field (`login_url`), its characteristics, and how it should be used, which is valuable since there are no parameters 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 description opens with a specific, action-oriented verb: 'Get a one-click, pre-authenticated dashboard sign-in link for the owner.' It clearly identifies the resource (a login link/token) and differentiates this tool from sibling dashboard/onboarding tools by focusing on the magic-link minting mechanism.

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

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

The description explicitly states when to use the tool: before dashboard tasks such as the engine-connect step, billing card updates, or accessing a project page. It also explains that the returned link should be sent to the user and that a fresh call is needed after expiry, providing clear contextual usage guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes further by clarifying the subtle behavior of `glm_peak_paused`, explicitly stating it is 'NOT a fault', 'sets no pause columns', and is an 'intentional cost gate'. It even provides reporting guidance ('report it as waiting for off-peak'), which prevents misinterpretation and adds genuine value beyond the structured annotations.

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

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

The description is concise and front-loaded: the first line states the purpose, the second lists outputs, and the third paragraph explains a critical nuance. Every sentence serves a purpose, and the caveat about `glm_peak_paused` is essential. No fluff or 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?

Given that a full output schema exists, the description does not need to enumerate all return fields. It highlights the most important ones and thoroughly explains the one field (`glm_peak_paused`) that could otherwise cause confusion. This makes the tool self-contained for an AI agent to invoke and interpret results correctly.

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

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

The schema defines `project_id` as a required string, and the description does not mention it at all (0% schema coverage). However, the parameter is inherently obvious from the tool's purpose and schema title, so the lack of additional explanation is not a significant gap. The description adds minimal value here, hence a mid-range score.

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

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

The description opens with a specific verb and resource ('Check how a project is doing') and elaborates with concrete aspects ('what is in flight, what shipped, what is stuck'), clearly distinguishing it from sibling tools like get_billing or get_onboarding_status. It also lists the exact return values, leaving no ambiguity about the tool's function.

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

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

The description provides clear context for when to use the tool: when checking a project's overall health, including lifecycle status, blockers, and freshness. It does not explicitly name alternatives or state when not to use it, but the context is unambiguous given the sibling tools cover unrelated domains.

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

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

Beyond the annotations, the description discloses what is preserved, what is granted, what is verified, and that the operation is transactional. It also confirms the idempotency annotation by calling itself idempotent. This does not contradict destructiveHint because it describes a careful mutation that resolves cards while preserving key 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?

Two compact sentences with the main purpose front-loaded and supporting behavioral details in the second sentence. Every phrase adds value, and the code-formatted escalation types and field names improve scannability.

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

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

For a one-parameter idempotent tool with an output schema, the description covers input type, verification, retry grant, preservation guarantees, and transactionality. It does not describe error cases or the exact return payload, but the output schema fills part of that gap.

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

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

Schema coverage is 0%, but the description compensates by defining the valid escalation-id categories for the single parameter. It makes clear the input must be either an 'expand_produced_nothing' or 'roadmap_item_parked' escalation id, which is essential semantic information not present in the schema.

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

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

The description names a specific action (re-arm), resource (same roadmap item dependency), and the required trigger (an escalation id). It clearly distinguishes this from sibling tools like resolve_escalation by explaining the actual re-arm behavior: verifying prerequisites, granting one retry, preserving dependencies, and resolving cards.

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

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

The description explicitly states which escalation types are valid inputs: 'expand_produced_nothing' or 'roadmap_item_parked'. This gives a clear condition for when the tool applies, though it does not name alternative tools or explicitly say when not to use it.

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

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

Annotations are all false, so the description carries the burden. It discloses the state transition (moves thread to refine_pending), the input constraint (feedback_md 1..2000 chars), and the precondition (status done). This is meaningful behavioral context beyond the annotations, though it doesn't cover reversibility or error handling.

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

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

The description is two sentences: the first states the purpose, the second packs the key constraints and state transition. No filler words. Every sentence earns its place, and the structure front-loads the primary intent.

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

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

Given the presence of an output schema (which handles return values), the description covers the essential behavioral contract: when to use (status done), what to provide (feedback_md), what happens (thread moves to refine_pending), and how to observe results (poll get_request_status). This is complete for a mutation tool of moderate complexity.

Complex tools with many parameters or behaviors need more documentation. 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. It does explain feedback_md's length constraint and purpose ('what is wrong'), but project_id and thread_id are left to their names, which are self-explanatory but not explicitly described. This is partial compensation, missing the opportunity to clarify the role of each parameter beyond the schema's bare definitions.

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

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

The description clearly states the tool's function: 'Say what is wrong with what a request produced, and have it reworked.' This is a specific verb+resource combination that distinguishes it from sibling tools like answer_request (answer a request) and submit_request (submit a new request). The context of reworking an existing request's output is unambiguous.

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

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

The description provides explicit usage context: the status must be 'done' before calling, and it instructs to poll get_request_status afterward to see revised items. It doesn't explicitly name alternatives or exclusions, but the precondition and next-step guidance effectively differentiate when to use this tool among the request-related siblings.

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

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

The description discloses important non-obvious behaviors beyond annotations: horizon pins override `ordered_ids`, unknown/non-queued ids are skipped, duplicates are rejected, and the response shape is {updated, queue, next_step}. This adds substantial behavioral context beyond the annotations' idempotent/non-destructive flags.

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

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

The description is well-structured: a one-line summary up front, followed by focused details on ordering semantics, pin interactions, edge cases, and return value. No filler or redundant restatement of the tool name or schema.

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

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

Given the tool's moderate complexity, the description covers the essential behavioral rules: priority interpretation, horizon pin precedence, ignored unknown ids, duplicate rejection, and result format. The output schema covers return structure, so the `returns` mention is a helpful 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 must carry parameter meaning. It thoroughly explains `ordered_ids`: desired front-to-back order, first id being highest priority, and handling of unknown/duplicate ids. `project_id` is not elaborated, but it is a simple identifier and the required usage is obvious 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?

The description opens with a clear statement of what the tool does ('Change what gets built first') and specifies the resource: the queue of roadmap items. It clearly distinguishes reordering from sibling tools like list_roadmap, cancel_roadmap_item, and clear_horizon_pin.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 to use this tool: to set the priority order of queued roadmap items, with guidance that ids come from list_roadmap. It does not explicitly name alternatives or state when not to use it, so it misses the full 'when-not/alternatives' bar.

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=true, and the description aligns with and enriches these by explaining the cancellation, lineage transfer, supersession provenance, and audit preservation. It also explicitly states that nothing is marked delivered, giving the agent a precise behavioral model beyond the annotations.

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

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

Two tight sentences: the first delivers the core purpose and scope, the second details behavioral consequences. Every clause contributes meaningful operational information with no filler or redundancy.

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

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

For a destructive, non-read-only tool with six required parameters and no schema property descriptions, the description provides strong lifecycle context: what gets created, what gets cancelled, what is preserved, and what is not delivered. It falls slightly short on per-parameter expectations and on explicit guidance about how to identify an 'unretryable' task, but the overall invocation context is well 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 must compensate for documenting what parameters like project_id, task_id, decision_md, and acceptance_criteria mean. It does not name or explain individual parameters, and while line good context, it leaves meaning to parameter-name inference rather than explicit description.

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

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

The description opens with a specific verb and resource: 'Replace an unretryable blocked task without losing its lineage.' It clearly states the operation's intent and its unique scope, distinguishing it from sibling tools like retry_blocked_task, close_task, and cancel_roadmap_item.

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

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

The description explicitly scopes usage to 'unretryable blocked task,' which tells the agent when this tool is appropriate and implicitly distinguishes it from retry_blocked_task. It does not explicitly name alternatives or state when-not-to-use conditions, but the context is clear enough.

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 that decision_md is appended as an audit trail to detail_md, that resolving a project_pause/orphan_pause 'RESUMES the project', and that the tool accepts a synthetic 'orphan:<project_id>' in addition to a UUID. The idempotent claim matches the annotation; 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?

Five dense sentences, each carrying operational information; the safety condition is front-loaded and the alternative usage is clearly separated. No filler or repetition beyond the single 'Idempotent' marker.

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

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

The description covers safety condition, parameter meaning, side effects, idempotency, and alternate routing to sibling tools. With an output schema present and annotations handling destructive/read-only signals, nothing essential is missing for an agent to select and 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?

With 0% schema coverage, the description fully compensates: decision_md is explained as a required short resolution note appended as audit trail, and escalation_id is defined by its accepted formats (real escalation UUID or synthetic orphan:<project_id>). Both required parameters get semantic meaning beyond raw string names.

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

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

The description opens with a specific verb and resource ('Acknowledge a handled ask') and adds a precise guarding condition ('only when no blocked task becomes invisible'). It later distinguishes this operation from sibling resolution paths, so an agent can identify what the 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?

It says exactly when to resolve ('only when no blocked task becomes invisible') and when not to: 'A blocked task's final task_block/operator_action cannot be acknowledged.' It explicitly names alternatives ('typed retry, platform-policy resolution, replan, close, or supersede operation'), which maps to sibling tools.

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

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

Annotations already mark the tool as destructive and idempotent, and the description adds real behavioral context: the decision becomes a task-plan section and the task lineage is requeued before the escalation resolves. This goes beyond the annotations, though it does not fully detail what 'remove_scenario' destructively changes.

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

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

The description is compact, front-loaded, and every sentence earns its place. The code-formatted decision values and conditional requirement are easy to scan, with no filler or repetition.

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

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

For a 4-parameter tool with an output schema, the description sufficiently covers the decision options, the conditional cap, and the post-decision behavior. The main missing pieces are the meaning of decision_md and explicit routing guidance, but an agent can invoke the tool correctly with what is provided.

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

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

With 0% schema description coverage, the description must explain the parameters itself. It effectively documents the decision enum and the conditional project_cap range (6..24), but it leaves escalation_id and decision_md unexplained, so compensation is only partial.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Resolve'), a specific resource ('platform-policy dead-end'), and a structured decision mechanism. It is clear and distinguishable in practice, but it does not explicitly contrast itself with the sibling resolve_escalation, so it stops short of a 5.

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

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

The usage context is implied by 'platform-policy dead-end' and the decision-oriented behavior, but there is no explicit when-to-use vs. when-not-to-use guidance relative to sibling tools like resolve_escalation. It gives operational context without naming alternatives or exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the server-side derivation of eligibility, tenant, etc., and notes idempotency (matching the annotation). However, it does not elaborate on the concrete effects of the retry (e.g., whether the block is cleared, what happens to existing state). Since destructive behavior is flagged but not detailed, the description carries only moderate extra value beyond annotations.

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

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

The description is three concise sentences. The primary action is front-loaded, followed by the required input, a note on server-side derivation, and a clear distinction from a sibling. No filler or repetition; every sentence adds value.

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

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

The tool has an output schema, so return handling is covered. Annotations provide destructive/idempotent flags. The description explains when to use and how to get one parameter, but the vague handling of decision_md and a slight naming inconsistency ('task_block id' vs 'escalation_id') leave gaps. For a two-parameter tool, missing half the parameter semantics is notable, though the overall purpose and usage are clear.

Complex tools with many parameters or behaviors need more documentation. 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. It explains that escalation_id (likely the 'task_block id' mentioned) should come from list_escalations, providing partial meaning. However, decision_md is completely unexplained, leaving the agent without guidance on what content or formatting is expected. With two required parameters and only one addressed, this is a significant 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?

The description clearly states a specific action ('Grant one fresh attempt after fixing a recovery-budget task block') and identifies the resource (task block). It explicitly distinguishes itself from the sibling 'resolve_escalation', making it easy to tell apart. The purpose is unambiguous and tied to a concrete use case.

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

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

Usage guidance is explicit: it tells the agent to pass the task_block id from list_escalations and explains that this tool is distinct from resolve_escalation, which is acknowledgement-only. It also implies the timing ('after fixing') and that eligibility is derived server-side. This fully directs the agent on when to use it versus the main alternative.

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

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

The description thoroughly discloses behavioral traits: it 'never rebuilds from source', 'mints a NEW Roblox version pointing at the old build', and lists specific error codes (404, 422, 409) with meanings. Annotations indicate destructiveHint=true and idempotentHint=false, which the description aligns with. It goes above annotations by detailing rate limits, invalid key handling, and the return payload. This is excellent transparency.

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

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

The description is well-organized: a lead sentence stating purpose, then a clause on how it works, then error scenario details, then the return shape. It is concise yet packed with necessary details, with no filler or fluff. Each sentence serves a distinct role, and the error code list is efficient.

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

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

Given the tool complexity (destructive operation, external platform interaction, error handling), the description is remarkably complete. It covers usage constraints, failure modes, retry guidance, and the output schema (though also present separately). With annotations and output schema, the description provides all necessary context for an agent to invoke it safely and correctly.

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

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

The input schema has 2 parameters, and schema description coverage is 0%. The description only mentions 'version_number' implicitly (it references getting published versions) but does not explain the meaning or constraints of 'project_id' or the exact syntax of 'version_number' (e.g., that it's an integer existing in the list). Since the schema itself provides only names and types, the description fails to add sufficient semantic elaboration to make parameter usage clear.

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

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

The description clearly states the tool's action: rolling back a Roblox project's place to a previously-published version. It specifies the resource ('place'), the operation ('roll back'), and adds context (for 'roblox_game' projects) and distinguishes it from rebuilding from source. It clearly differentiates from sibling tools like update or publish by focusing on rolling back to a retained artifact.

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

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

It provides clear usage context: it's for roblox_game projects, and tells the agent to get published versions from the web Roblox Publishing card. It also infers when to use it (when rolling back is needed) but does not explicitly mention alternatives or exclusions (e.g., 'use this only when you need to revert to a published version, not for normal updates'). However, given the limited sibling tool set, this is adequate.

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 contradicts the annotation 'readOnlyHint: false' by stating 'it does not make changes'. This is a significant inconsistency that overrides the other transparency disclosures (billable, concurrency limit, refusal behavior). Per rubric, contradiction forces a score of 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?

The description is two short paragraphs, efficiently covering the purpose, prerequisites, constraints, and refusal behavior. It is well-structured and avoids unnecessary verbosity.

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

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

It explains the refusal case (ok: false) and prerequisites, but does not describe the success response or the overall workflow. Since no output schema is provided, this gap reduces completeness.

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

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

Only one parameter 'project_id' exists and is not further explained, but the name is self-explanatory. The description mentions 'one project' but does not add details beyond the schema. With 100% schema coverage, baseline is 3.

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

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

The description clearly states it starts a security control gap review for a project, with a specific focus on Cyber Essentials or CMMC levels. It distinguishes from sibling tools like 'run_security_review' and 'run_legal_exposure_review' by the 'control gap' and 'source-bound' qualifiers.

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

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

It provides prerequisites (saved framework profile, eligible plan, allowlist) and constraints (billable, one in-flight per project). While it does not explicitly contrast with sibling tools, the scope is clear enough for an agent to select it for control gap reviews.

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 annotation readOnlyHint=false and idempotentHint=false are partially contradicted by the text 'No change is ever applied automatically' and 'one-shot review' - the tool creates review artifacts but does not mutate code, so the readOnly flag is misleading though not a direct 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 description is long but dense: every sentence behooves the safety- and legal-critical subject matter; the disclaimer, concurrency, billing, and permit requirements are all condensed into compact prose. The paragraph structure is preserved along with the front-loaded core purpose.

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

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

For a complex tool with schema, annotations, output schema, and heavy operational context, the description covers the prerequisites, side effects, billing/permissions, failure mode, and result access method. Minor gap: no return value description but output schema makes it less relevant.

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

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

With one param (project_id) and 0% schema_description_coverage, the description should compensate by explaining the required format, prerequisite profile, or project_id semantics but it does not go beyond the name and the requirement. The agent would need to infer project_id meaning entirely from other contexts.

Input schemas describe structure but not intent. Descriptions should explain 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 ('find where a codebase creates legal exposure') and details the mapping to legal obligations, making the primary purpose unmistakable and distinct from generic review tools.

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

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

Provides concrete prerequisites (saved compliance profile, project on allowlist, feature flag), billing/concurrency caveats, and disclaimers. It does not explicitly name alternative tools for comparison, but the caveats establish when not to use it.

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

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

The description goes far beyond the annotations: it explains the one-shot, non-idempotent nature, that findings are posted for human triage and no fixes are applied automatically, that the action is billable, that only one audit can be in-flight per project, and that triggering is disabled unless the project is on an operator allowlist. It complements the annotations (readOnlyHint false, idempotentHint false) without contradicting them.

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

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

The description opens with a clear one-sentence purpose, then uses scannable paragraphs for behavioral details, constraints, and prerequisites. Every sentence adds meaningful information: taxonomy content, workflow, billing, in-flight limit, allowlist, and plan requirement. There is no filler and no repetition of annotation-schema data.

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

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

For a complex security-review tool, the description is remarkably complete: it covers the input, the analysis scope, the output destination, the human-in-the-loop workflow, filtering, cost, concurrency, and access restrictions. The output schema provides return details, and the description fills in operational context that the output schema cannot express.

Complex tools with many parameters or behaviors need more documentation. 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 only one parameter and 0% schema description coverage, the description compensates partially by repeatedly referencing 'project' (project's Security review, one audit per project, project allowlist). It does not explicitly say 'project_id is the identifier of the repository to scan', but the single parameter is simple and the context strongly implies that meaning. A more explicit mapping would be ideal, but it is adequate for a single-parameter 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?

The description uses a specific verb-resource combination ('Find security problems in a repository') and immediately distinguishes the tool from siblings like run_control_gap_review and run_legal_exposure_review by emphasizing a deep, whole-codebase security audit. It also names concrete categories (secrets, deps, injection, SSRF, etc.) that pin down its unique scope.

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

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

The description clearly states when to use the tool (to find security problems, including specific vulnerability classes) and gives operational constraints (billable, one audit in-flight, allowlist gating, paid plan). It does not explicitly name alternative tools or say 'use run_control_gap_review for compliance gaps', but the context of sibling tools makes the intended use reasonably 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?

Annotations already indicate mutation and idempotency, but the description adds useful behavioral detail: goal_md must be non-empty, tenant scoping can cause a 404, and the call returns a predictable object with updated_at and next_step. This exceeds what the annotations alone provide.

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

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

The description is compact and front-loaded: one key sentence, a parameter note, and a brief return contract. No filler or redundant restatement of the tool name.

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

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

The description covers purpose, key constraint, tenant-scoping error behavior, and return shape. With only two required params and no nested objects, this is sufficient without being verbose.

Complex tools with many parameters or behaviors need more documentation. 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 provides zero description coverage, so the description must carry the load. It explains goal_md as free-form non-empty markdown and implies project_id identifies the target project via the tenant-scoped 404 behavior. This is meaningful semantic guidance, though it leaves project_id format unspecified.

Input schemas describe structure but not intent. Descriptions should explain 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 phrase ('Set the outcome to aim at right now') and clearly identifies the resource (the project's product goal). It differentiates from the sibling set_product_vision by emphasizing the immediate focus ('right now') rather than a broader vision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 conveys when to use the tool: when work needs to be prioritized toward one current outcome. It does not explicitly discuss when not to use it or name alternatives, but the context is clear enough for basic selection among siblings.

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

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

Description adds substantial behavioral details beyond annotations: tenant-scoping ('a project not in the caller's workspace 404s'), the non-emptiness constraint on vision_md, the return shape ({project_id, product_vision_md, updated_at, next_step}), and the purpose 'so every run knows what it is building toward'. Annotations (idempotentHint=true, destructiveHint=false) align with the described behavior, and the description enhances understanding without 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 description is compact (three sentences), with the primary purpose stated upfront in the first line. Code formatting and a newline improve readability. Every clause adds value—constraints, scoping, return type—without redundancy. It is appropriately sized for a 2-parameter tool.

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

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

The description covers all critical aspects: what the tool does, field constraints, tenant scope, error behavior, and return structure. It is fully self-contained for an agent to invoke it correctly, especially since the output schema is already declared externally. No further details are needed for typical usage.

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

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

With 0% schema coverage, the description compensates by clarifying vision_md as 'free-form markdown' with the 'must be non-empty' constraint. project_id's semantics are only indirectly explained through 'a project not in the caller's workspace', which hints at its identifier nature. While the description does not explicitly enumerate each parameter, it provides functional meaning that goes beyond the field names alone, making this a strong compensation for the lack of schema documentation.

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

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

Description clearly states the tool's function: 'Say what this product is for', using a verb-object structure that directly maps to the tool name. It defines the resource (product vision) and differentiates from siblings like set_product_goal by focusing on the vision, not goal. The phrasing is specific and unambiguous.

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

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

No explicit guidance on when to use this tool vs. alternatives, nor any mention of when not to use it. While the purpose is implied by the name, there is no discussion of prerequisites, differences from similar tools, or use cases. This is a clear gap given the rich sibling set includes set_product_goal, which could conceptually overlap in intent.

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 annotations (idempotentHint=true, readOnlyHint=false), the description discloses important non-obvious behavior: the screenshot cap derives from scenario_cap, enforcement happens on keelen pushes rather than in CI, an over-cap manifest fails every push while CI stays green, and repeated identical calls change 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?

The description is dense but every sentence earns its place: reset semantics, valid values, derived cap behavior, raising/lowering constraints, enforcement timing, pre-read instruction, and idempotency. It is front-loaded with the core purpose and organized from basics to edge cases.

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

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

For a mutating configuration tool with two parameters, the description covers preconditions, refusal conditions, default values, enforcement behavior, and idempotency. An output schema exists, so omitting return-value details is acceptable. An agent has enough context to invoke this tool correctly without guessing.

Complex tools with many parameters or behaviors need more documentation. 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 thoroughly explains scenario_cap's valid range (6-24), the null reset value (12), and the derived screenshot cap. project_id is not explicitly detailed, but 'this web_app project's' in the opening makes it clear enough.

Input schemas describe structure but not intent. Descriptions should explain 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 is a concrete verb+resource statement: 'Set this web_app project's ui-review scenario budget, or reset it.' It clearly identifies the resource, the action, and the scope, making it easy to distinguish from sibling setters like set_product_goal and set_product_vision.

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

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

The description provides strong usage guidance: read project_status.ui_review first, raising is always allowed, lowering is refused when the manifest declares more scenarios/screenshots or cannot be read, and repeated calls with the same value are no-ops. It gives the agent clear preconditions and failure modes.

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 far beyond annotations: email delivery, 15-minute code expiry, rate limits per IP and email, enumeration-safe responses, and the dual-purpose login behavior. Annotations (readOnlyHint=false, openWorldHint=true) are consistent and the description adds contextual safety warnings that are essential for a signup 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?

Although the description is long, it is densely packed with actionable information: a clear purpose, flow, timeouts, rate limits, safety warnings, and user-interaction directives. Every sentence serves a purpose, and the structure front-loads the core action then builds context, making it highly scannable.

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

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

The tool is complex—it doubles as login, has security and enumeration concerns, and is the entry point for the whole setup flow. The description covers all relevant aspects: authentication context, the exact email/verify/save sequence, rate limits, expiration, and the need to ask the user. Given the presence of an output schema (though not detailed here), the description is sufficiently complete for an agent to operate it correctly.

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

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

With schema coverage at 0% (the schema only labels the parameter 'Email'), the description fully compensates by explaining that 'email' is the destination for the code and by instructing the agent on proper acquisition (ask user, never infer). It also clarifies the security implications of the parameter value, which goes well beyond the schema.

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

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

The description opens with a definitive verb and resource: 'Create a Keelen account (or start agent login) — emails a 6-digit code.' It clearly distinguishes from sibling tools like verify_email and get_onboarding_status, and explicitly states both the account creation and login angle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance is explicit: marks the tool as UNAUTHENTICATED and the only one (besides verify_email) that works pre-auth, then provides the full flow sequence. It also instructs the agent to ask the user for email and wait, explicitly forbidding inference from ambient sources. It names the alternative verify_email and warns against guessing due to login implications.

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 all neutral (false), so the description carries the disclosure burden. It reveals that the call returns a thread_id, status, next_action, poll_after_seconds, and next_step, implying an async pattern. It also specifies a 16000-character limit for text, which is a concrete behavioral constraint. It does not detail side effects or error conditions, but it goes beyond annotations by describing the return contract and polling behavior.

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

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

The description is two concise sentences followed by a clear return-value line. It is front-loaded with the purpose, then provides usage guidelines and output details. Every sentence adds information with no fluff or 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?

The tool is moderately complex (async with polling), and the description addresses the key workflow: submit, receive thread_id, and follow next_step. It includes the return fields and length constraint. However, it omits any explanation of project_id and does not cover error handling or prerequisites, but given the output schema is provided, the return contract is sufficiently communicated.

Complex tools with many parameters or behaviors need more documentation. 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 both parameters. The description only mentions text, giving a length limit but not its semantic purpose. project_id is completely unexplained, which is a significant gap for a required parameter. Despite the low coverage, the description only partially compensates, earning a score below the baseline of 3.

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

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

The description clearly states that the tool submits a change request (feature, bug fix, or new direction) in plain English. It specifies the action (submit) and resource (request), and distinguishes from siblings like answer_request (responding) and refine_request (modifying an existing request) by emphasizing submission of one new intent per call.

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

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

It explicitly says to submit one feature or intent per call and to split multi-feature asks, which guides usage. It also instructs to follow the returned next_step and poll via get_request_status. However, it does not explicitly name alternative tools for different use cases (like refine_request for existing requests), so it stops short of a full when-not-to-use comparison.

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 indicate a mutating, non-idempotent operation, but the description adds substantial context: the key is shown exactly once, there is a 5-attempt maximum, a 15-minute expiration, a uniform error response, and explicit storage security guidance. No contradiction with annotations.

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

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

The description is information-dense but every sentence earns its place: purpose, authentication context, attempt/expiry constraints, one-time key warning, and recovery path. The first sentence is the clear summary and all follow-up details are actionable.

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

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

Given the tool's authentication role, the description covers prerequisites (code from signup), constraints (15 minutes, 5 attempts, one-time reveal), postconditions (store in MCP client config, reconnect), and failure handling. With an output schema present for return value details, this is fully complete.

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

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

Schema description coverage is 0%, so the description carries the full semantic burden. It connects `email` and `code` to the signup flow, specifies the code is 6-digit, and explains the match requirement. It does not detail format validation for email, but the relationship to signup(email) provides sufficient 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 opening sentence 'Redeem the emailed 6-digit code for a reveal-once workspace API key' uses a specific verb ('redeem'), names the resource (emailed code, API key), and clearly distinguishes this from sibling tools like signup (which issues the code) and get_onboarding_status (which follows authentication).

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

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

The description explicitly states when to use the tool ('UNAUTHENTICATED', code issued by signup within 15 minutes), gives an alternative ('call signup(email) for a fresh one' on invalid/expired/consumed codes), and provides the next step ('Then reconnect... call get_onboarding_status()').

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