Keelen

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

No annotations are provided, so the description carries the burden. It discloses the side effect: 'Flips the thread back to intake_pending' and instructs to poll get_request_status again. It also specifies the answer format constraints (1..2000 chars). However, it doesn't mention potential errors or idempotency, but given the context, it's fairly transparent.

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

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

The description is concise and well-structured. It front-loads the purpose, then provides parameter details and post-conditions in a clear, scannable format. 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?

Given the tool's complexity (list of answers, status transitions), the description covers the essential workflow: precondition, answer format, and post-action. It references get_request_status for indices and polling, which is helpful. It doesn't describe the output schema, but since an output schema exists, that's acceptable. Minor gap: it doesn't specify what happens if the thread is not in awaiting_answers status, but the precondition implies it.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'answers' parameter structure in detail: list of objects with 'idx' (from get_request_status) and 'answer_md' (string, 1..2000 chars). It also clarifies that every question must be answered exactly once. project_id and thread_id are self-explanatory from their names, but the description doesn't explicitly mention them; however, they are standard identifiers.

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

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

The description clearly states the tool's purpose: 'Answer a thread's clarifying questions' with a specific precondition (status must be awaiting_answers). It distinguishes from siblings like submit_request and refine_request by focusing on answering clarifying questions in a thread.

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

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

It explicitly states when to use: when the thread status is awaiting_answers, and provides a clear workflow: answer every question exactly once, then poll get_request_status again. It also implies not to use when status is not awaiting_answers, and references get_request_status as the source for question indices.

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?

No annotations are provided, so the description carries the full burden. It discloses stopping in-flight machines, freeing a slot, idempotency, reversibility, owner-only scope, and 404 behavior. This is thorough behavioral transparency.

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

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

The description is concise and well-structured: a clear lead sentence, then a multi-line explanation of effects, idempotency, and alternative. No fluff, all information is 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 moderate complexity (side effects, reversibility, scoping) and lack of annotations, the description is quite complete. It covers behavioral effects, restoration path, and error condition. The output schema exists but description doesn't repeat it, which is fine.

Complex tools with many parameters or behaviors need more documentation. 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 project_id with no description. The tool description mentions 'project not in the workspace 404s' and 'owner-only', giving context, but doesn't explicitly define the parameter. Since schema coverage is 0%, description compensates minimally but adequately for a single obvious parameter.

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

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

The description clearly states the action: 'Archive a project (reversible shelve)' and explains the effect ('frees a project slot', 'flips the project to archived'). It also distinguishes from delete_project, making it clear what this tool does and how it differs from its sibling.

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

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

Explicitly says 'Prefer this over delete_project unless you specifically want the project gone', providing a clear when-to-use guideline and an alternative. It also notes owner-scoping and error condition (404 if not in workspace). This is actionable 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?

With no annotations, the description discloses key behaviors: dropping from expand queue, resolving open escalations, idempotency, 409 error during active expansion, and the return shape. This fully compensates for missing 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 moderately long but well-structured: a concise lead sentence followed by rationale and behavior details. No redundancy or irrelevant 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?

Despite no output schema, the description specifies the return object ({id, status, changed, next_step}) and covers side effects, error conditions, and idempotency, making it complete for the tool's context.

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

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

Schema only provides titles—no descriptions. The description adds guidance for item_id ('get its id from list_roadmap') but does not clarify project_id or other details. Partial compensation for low schema coverage.

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

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

Clearly states the action (cancel/close a roadmap item) and distinguishes it from listing tools. Explains the intended use case (closing delivered or duplicate items) to avoid confusion with expand or other operations.

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

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

Provides explicit guidance on when to use: for DELIVERED or duplicate items that keep re-parking, and mentions conditions (idempotent, 409 during active expansion). Implicitly contrasts with expand/list 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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals the side effects (unpins and reprices the queue), the error condition (422 on non-queued items), and the return shape ({id, previous_pin, horizon_pin, next_step}). It also explains the domain rule that in-flight/shipped items derive their pin rather than having a settable one.

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

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

The description is a single focused paragraph that front-loads the key action and follows with necessary context. Every sentence earns its place: the purpose, the problem it solves, the limitation, and the return value. It is detailed but not bloated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 interaction with queue sorting, reorder_roadmap, and cancel_roadmap_item, the description covers the operational context, the error case, and the return values. The output schema exists, and the description complements it by explaining the next_step semantics and the 422 error, making it sufficiently 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?

The schema description coverage is 0%, so the description must compensate for the bare parameter names. It does provide context that 'item_id' refers to a queued roadmap item and that project scope matters, but it never explicitly states that item_id is the roadmap item ID or that project_id identifies the owning project. The meaning is inferable but not fully spelled out.

Input schemas describe structure but not intent. Descriptions should explain 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+scope: 'Clear a queued roadmap item's horizon pin (now/next/later → none).' It clearly distinguishes this from sibling tools like reorder_roadmap and cancel_roadmap_item by specifying exactly what operation is performed and on what entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 context: it explains that a pinned item dominates the queue sort and that reorder_roadmap cannot move a pinned item, so this tool is the right choice for unpinning stale items. It also states when-not-to-use: it refuses non-queued items and directs the agent to cancel_roadmap_item for delivered items.

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

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

With no annotations provided, the description carries full transparency burden. It discloses that the tool returns a URL, that user approval is required, that polling is necessary, and that the link expires. It also implies that repeated calls may be needed, but the behavior is fully disclosed within the description.

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

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

The description is concise yet complete, covering the essential steps (send link, user approves, poll status) and the expiration caveat in a structured manner. Every sentence adds value; no fluff 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?

The description is fully self-contained for a tool with no parameters and no output schema. It explains what is returned (install_url), how to use it, the follow-up polling step, and the expiration behavior. It also references get_onboarding_status() for clarity, making it contextually 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?

The tool has zero parameters, so schema coverage is 100% (trivially). Per rubric, high schema coverage yields a baseline of 3 even without parameter-specific descriptions. There is no parameter information to add, so the score remains at the baseline.

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

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

The description clearly states the tool's function: it mints a GitHub App install link for the workspace owner to connect GitHub. The verb 'mint' is specific, and the resource is clearly identified. It distinguishes itself from other tools by focusing on the GitHub connection flow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 instructions: send the returned URL to the user, wait for approval, then poll get_onboarding_status() until github_connected is true. It also notes the 10-minute expiration and advises calling connect_github() again for a fresh link, making the usage clear and actionable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fully delivers: explains exactly what enable/disable do (flip scheduler_enabled), what the loop dispatches (only enabled, status='active' projects), what resume clears (pause types), and the precise no-op conditions for process_now. It even states the return value, making the tool's behavior highly predictable.

Agents need to know what a tool does to the 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 well-structured: a one-sentence lead gives the tool's purpose, followed by a bulleted list of the four actions with precise behavioral effects, and a final sentence about the return value. Every sentence carries meaningful information, and the front-loaded lead enables quick understanding.

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

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

Given the tool's moderate complexity (2 required params, no annotations, output schema present), the description is highly complete. It covers all action variants, their side effects, no-op edge cases, and the return value. The output schema handles return shape specifics, so the description's omission of exact state format is appropriate. No meaningful gaps remain for invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It thoroughly documents the `action` parameter by listing all four valid values and their meanings, and even explains the output state. `project_id` is not explicitly defined, but its name plus the phrase 'a project's scheduler' make it unambiguous. This is strong compensation for a low-coverage schema, though the project_id parameter could have been mentioned explicitly.

Input schemas describe structure but not intent. Descriptions should explain 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 'Enable/disable, resume, or process-now a project's scheduler', which precisely identifies the resource (a project's scheduler) and the distinct operations. It clearly differentiates from sibling tools like run_control_gap_review or run_security_review, which are unrelated review actions, and project_status which is a read-only status check.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies when to use the tool: whenever you need to change the operational state of a project's scheduler. It enumerates four distinct actions and their semantics, providing clear context for each. However, it does not explicitly state when not to use the tool or name alternative tools, so it falls short of the 'explicit when/when-not/alternatives' benchmark.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains side effects (creates GitHub repo, bootstrap-mode project, submits Roadmap Request), auth requirements (repo-create OAuth access), error conditions (no member access, org restrictions), and return behavior (follow next_step). It doesn't mention reversibility or rate limits, but covers key behavioral traits comprehensively.

Agents need to know what a tool does to the 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 well-structured, front-loading the core purpose and usage guidance, then systematically covering parameters. Each sentence adds value, though it could be slightly more concise by grouping related parameter details. The use of backticks and clear parameter names aids readability.

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

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

Given the tool's complexity (9 parameters, 3 required, multiple interdependencies, no annotations, no schema descriptions), the description is remarkably complete. It covers all parameters, return values, error cases, and follow-up actions. The output schema exists, so return values are partially covered, but the description adds crucial context about next_step and error handling.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains each parameter's meaning, constraints, defaults, and interdependencies (e.g., preview_command required iff project_kind == 'web_app', framework is web_app-only, engine defaults to claude_code). It also clarifies the semantics of name as a short repo slug and org as an optional organization login.

Input schemas describe structure but not intent. Descriptions should explain 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 creates a brand-new from-scratch project, explicitly distinguishing it from import_project for existing repos. It specifies the verb (create), resource (project), and scope (new repo scaffolded), which differentiates it from siblings like import_project and list_github_repos.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 guidance ('Use this ONLY when the user wants a NEW repo scaffolded') and when-not-to-use with alternatives ('If they already have a repo, use import_project(repo_full_name) instead'). It also mentions list_github_repos() for browsing, giving clear context for tool selection.

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

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

Discloses all significant side effects: stops in-flight machine, flips state to deleted, removes from list and cap, stops dispatching, retains row for audit but no restore. Also notes idempotency. No annotations provided, so this description fully compensates.

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

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

Two concise paragraphs are front-loaded with the key action and effect. Every sentence adds value—no fluff—while covering all important behavioral nuances.

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

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

Given the tool's complexity (soft delete with side effects) and lack of annotations, the description is fully complete: it covers process changes, side effects, idempotency, restore options, and error conditions. An output schema exists, so return format need not be described.

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

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

Schema coverage is 0%, and the only parameter is `project_id`. The description adds semantic context by clarifying ownership scope and error behavior ('Owner-scoped; a project not in the workspace 404s'), which gives the ID meaning beyond a simple string.

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

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

The description explicitly states the action: 'Soft-delete a project (the harder option) — frees a slot and hides it.' It defines the scope and outcome, and explicitly contrasts with `archive_project`, distinguishing it from 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?

Guidance is explicit: it tells when to use this over `archive_project` ('unlike `archive_project`') and states the irreversible nature (`NO in-tool restore`), plus provides operational details like owner-scoping and 404 behavior for non-workspace projects.

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

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

With no annotations, the description fully discloses important behaviors: checkout_url has next_action 'browser', compute unlocks automatically via a Stripe webhook, and the model should not block on it. It also warns that a past_due workspace must not receive a new checkout because it would create a duplicate subscription. This is exemplary transparency for a tool with side effects.

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

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

The description is appropriately dense and well-structured. It leads with the core purpose, then explains conditional outcomes in a logical flow. Every sentence contributes meaningful information about when and how to use the tool, with no filler.

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

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

Given the tool's conditional behavior, the description covers all major states: no subscription, past_due, subscribed, and suspended-with-subscription. It also explains the webhook-driven activation and the next_step field. The presence of an output schema means return-value details are already structured, so the description is complete for decision-making.

Complex tools with many parameters or behaviors need more documentation. 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 lists a plan string with a default, but the description adds the allowed values 'starter | pro | agency' and confirms the default. Since schema description coverage is 0%, this compensation is essential and fully clarifies the parameter's meaning.

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

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

The description clearly defines the tool as returning billing status plus a Stripe checkout link when a new subscription is needed. It uses specific verbs and resources and differentiates from sibling tools by focusing on billing/subscription state. The nuanced conditional behavior makes the purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: when a workspace has no live subscription and needs one, return the checkout URL for the user to open in a browser. It also gives a clear when-not case: past_due workspaces should not get a checkout and instead need a card update in the dashboard. This is strong usage context beyond a generic description.

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?

Given no annotations are provided, the description takes full responsibility for behavioral disclosure. It explicitly states the tool is read-only, has no compute quota, remains available after the trigger closes, and details grouping behavior (by evidence class, no total). It also warns that empty groups do not imply control is in place, providing crucial context for interpreting results.

Agents need to know what a tool does to the 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 with a clear opening sentence, then a paragraph of critical usage notes, followed by parameter details. It is concise, with every sentence adding value—no filler or redundancy. The information is front-loaded with the 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?

Given the tool's complexity (grouping, edge cases like empty groups, disclaimer), the description covers all essential aspects: behavior, parameter semantics, and critical interpretation warnings. The output schema likely provides return structure, so the description doesn't need to repeat that. The description is comprehensive for safe and correct usage.

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

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

Schema description coverage is 0%, but the description compensates by explaining the semantics of key parameters: 'limit' defaults to 25 (max 100), and 'include_all' includes resolved, dismissed, and out-of-scope records. project_id is implied by the tool's purpose as the project to read. This provides critical context 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 clearly states the tool reads a project's security-control observations and review boundaries, distinguishing it from sibling tools like run_control_gap_review which likely initiates the review. It specifies the resource (project) and the action (read/fetch), making the purpose 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?

The description provides explicit guidance on when to use this tool: to read observations and review boundaries, and it contrasts with run_control_gap_review by being read-only. It also includes important usage notes such as reading not_determinable and outside_review_scope before describing observations, and that disclaimer_md must reach the user, which clarifies correct usage.

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

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

With no annotations provided, the description fully discloses behavior: it states 'Read-only, no compute, no rate limit,' clarifies that 'exposure_order' is an ORDER (not a score), notes that 'counsel_reviewed' is currently false for all entries, and explains the meaning of include_all. This gives the agent a complete picture of side effects and semantics.

Agents need to know what a tool does to the 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 somewhat long but every sentence earns its place. It front-loads the purpose, then provides essential output details, usage caveats, and parameter clarifications. There is no redundant or filler content, though a slightly tighter structure could 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?

Given the tool's complexity (3 parameters) and the presence of an output schema, the description is notably complete. It explains output fields (OBSERVATION, obligation, citation, date, counsel_reviewed), warns about interpretation pitfalls ('exposure_order' is not a score), and covers edge cases (not_determinable, include_all). No significant gaps remain.

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

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

Despite 0% schema description coverage, the description compensates for parameter semantics: it explains 'limit' defaults to 25 (max 100) and 'include_all' adds resolved, dismissed, and out-of-scope rows. The project_id parameter is self-evident. The description adds meaningful context 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 function: 'Read a project's legal exposure findings, worst exposure first.' It specifies the resource (project's legal exposure findings) and the ordering, distinguishing it from sibling tools like 'get_control_gap_findings' (different domain). The purpose is unambiguous and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 directives: it instructs the agent to read 'not_determinable' before summarising to avoid partial results, mandates that 'disclaimer_md' must reach the user, and clarifies that the tool works even when the project trigger is closed. It does not explicitly mention when not to use this tool versus alternatives, but the context is clear and actionable.

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

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

No annotations exist, so the description must carry the full behavioral burden, and it does. It discloses the polling behavior (server does not push), the deprecation of next_action_detail with a removal date, and critically explains security constraints around engine subscriptions requiring dashboard connection, never asking for credentials.

Agents need to know what a tool does to the 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 but dense with actionable information. Every sentence adds value: status fields, next_action semantics, deprecation notice, step-by-step tool recommendations, and security instructions. It is well-structured with bullet-like sections (engine/github/project/launch steps) and front-loads the most critical instruction (follow next_action verbatim).

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

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

The description is complete for a complex orchestration tool. It references sibling tools that the agent can call based on progress, explains the polling model, flags a deprecated field with a removal date, and covers security constraints. The output schema exists, so return format details are covered structurally, but the description adds critical interpretation guidance beyond that.

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

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

The tool has zero parameters and the schema is empty, so the baseline is 4. The description goes beyond by explaining what the response contains and how the output fields should be interpreted, though it doesn't need to compensate for missing parameter docs since there are none.

Input schemas describe structure but not intent. Descriptions should explain 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 reports onboarding status and provides actionable next steps. It specifies the exact fields returned (engine_connected, github_connected, project_count, payment_status, next_action) and distinguishes itself from siblings like get_provisioning_status which is for a later launch step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 and how to use the tool: poll between steps, follow next_action verbatim, and it names sibling tools to call for each onboarding step (connect_github, create_project, import_project, get_provisioning_status). It also warns against asking for engine credentials, and explains the polling model.

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

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

With no annotations, the description carries the full burden. It discloses polling behavior, the meaning of next_action, and the fact that 'ready' marks onboarding complete. It lacks details on rate limiting or broader side effects, but the status-checking nature is implicitly safe. The description adds context beyond the schema, but could be more explicit about idempotency.

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

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

The description is concise and front-loaded: the first sentence states the purpose, followed by clear details on the return structure and suggested actions. Every sentence adds value without fluff, fitting within a few lines.

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

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

Given the tool's complexity (polling behavior, error handling, integration with submit_request) and that the output schema exists (so return format is documented), the description covers the essential workflow. It could explicitly mention the expected polling loop duration or exit conditions, but for a status-checking tool, it is adequate.

Complex tools with many parameters or behaviors need more documentation. 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, project_id, has no schema description (0% coverage), so the description must compensate. It does mention the project must be in the caller's workspace and that it refers to a freshly created/imported project, giving context that a bare schema lacks. However, it does not explicitly state the format or type beyond the schema's string type.

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

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

The description clearly states the tool's function: retrieving provisioning stages for a newly created/imported project, including overall status, checklist, and error kind. It distinguishes itself from siblings like get_onboarding_status and project_status by specifying the provisioning context and the exact response 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 explicitly directs the agent on when to use this tool: to poll while provisioning or errored, and to switch to submit_request when overall is 'ready'. It also warns that projects not in the caller's workspace result in a 404, guiding appropriate error handling and scoping.

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

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

With no annotations, the description carries the burden. It transparently states the async behavior, polling cadence, and possible outcomes (wait, answer_questions, done, cancelled, failed). It does not mention side effects (it's a read), but this is implicitly clear. Minor missing details like authentication or rate limits could be expected but are not essential.

Agents need to know what a tool does to the 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 well-structured. It uses bullet-like lines to list the next_action possibilities, making it easy to parse. Every sentence adds value, with no redundant 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 covers the essential context: async nature, polling, and the meaning of each next_action. The output schema presumably defines the exact return shape, so it doesn't need to explain that. It is complete for the intended use, though it could mention that the status is read-only (implied).

Complex tools with many parameters or behaviors need more documentation. 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 provides no descriptions for the two parameters (project_id and thread_id). The parameter names are self-explanatory, but the description does not add any context or clarification beyond the names. Since there is no additional explanation, the semantics are only partially conveyed.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Get intake status + clarifying questions for a submitted request.' The verb 'get' and resource 'request status' are specific, and it distinguishes itself from sibling tools by focusing on status retrieval.

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

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

The description explicitly explains when to use it: 'Intake is async (~5min cadence) - poll periodically.' It also details the expected next_action values and their meanings, guiding the agent on how to interpret and respond to the status.

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

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

With no annotations, the description fully discloses behavior: idempotent re-imports, plan-limited behavior (loop OFF), 404 on non-visible repos, credential requirements for engines, and project_kind blocking the dev lane. It also mentions that passed project_kind is authoritative and never overwritten. This is comprehensive and beyond what annotations would have provided.

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

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

The description is long but each sentence carries necessary information. It is front-loaded with the core action, then systematically documents each parameter and edge case. No redundancy or filler; the structure flows logically from general usage to parameter details to post-import behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 includes post-import steps (follow next_step, poll get_provisioning_status), references sibling tools for discovery (list_github_repos, get_billing), and covers edge cases like monorepos and billing restrictions. Even with an output schema present, it enriches context enough for an agent to execute without additional lookups.

Complex tools with many parameters or behaviors need more documentation. 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%, but the description compensates fully. It explains repo_full_name format, all optional values for engine and project_kind with defaults, the purpose of build_description, preview_command requirements, and stack semantics. Every parameter gets meaningful context that the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain 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 'Connect an EXISTING GitHub repo as a Keelen project' with a specific verb and resource. It explicitly distinguishes itself from create_project, making the purpose unambiguous and differentiating it from 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?

Provides explicit usage guidance: 'use THIS tool when the user already has a repo, and create_project only to scaffold a brand-new one.' It also details when to pass project_kind manually (monorepos, non-standard stacks) and references sibling tools like list_github_repos and submit_request, leaving no ambiguity about when to use this tool.

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

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

With no annotations, the description carries full responsibility. It discloses the returned fields, the synthetic orphan row for forever-paused projects, and the relationship to resolve_escalation. It does not mention pagination or failure cases, but the core behavior is well explained.

Agents need to know what a tool does to the 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 succinct with two focused paragraphs. The first sentence states the purpose, followed by essential details on output and related tools. No redundant phrasing—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?

Given the output schema exists and the tool is relatively simple, the description covers the key behavior, edge case (orphan), and field list. It omits failure scenarios or prerequisites, but these are not critical for this read-only list tool. It is adequately complete.

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

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

The schema provides only project_id with no description (0% coverage). The description explicitly states the tool lists escalations for a project, making the single parameter's meaning clear. It also adds nuance about the orphan row being keyed by project_id, enriching the parameter semantics.

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

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

The description clearly states the tool lists OPEN escalations for a project, using a specific verb and resource. It distinguishes itself from project_status (which only counts) and resolve_escalation (which resolves), making the purpose unmistakable.

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

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

The description explicitly contrasts with project_status ('only COUNTS open escalations; this returns each one') and instructs to pass returned IDs to resolve_escalation, providing clear context for when to use this tool. It lacks an explicit 'when not to use' but the comparison covers 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?

With no annotations provided, the description carries the burden and does well by disclosing the key error state ('Returns 409 if GitHub isn't connected yet') and the remediation step. Losing a point only because it doesn't detail other potential errors or behaviors, but it's highly transparent for the main edge case.

Agents need to know what a tool does to the 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 follows a logical flow: what it does, what it returns, then a critical error case with a clear directive. Every sentence earns its place.

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

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

For a simple list operation with no parameters, this description covers all necessary context: the purpose, return fields, workflow integration, and error handling. The presence of an output schema means not having to explain return structure in the description, but it adds specificity beyond that.

Complex tools with many parameters or behaviors need more documentation. 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 parameters and schema coverage at 100%, the description adds significant value by explaining what data is returned ('full_name, default_branch, private, language, pushed_at') and how to use that data in conjunction with the sibling tool import_project().

Input schemas describe structure but not intent. Descriptions should explain 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 ('List repos the workspace's GitHub connection can see') with a designated purpose ('for import_project'). It definitively distinguishes itself from siblings like connect_github and import_project by showing its role in the workflow.

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

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

It gives explicit context on when to use the tool ('for import_project') and provides crucial 'when-not' and prerequisite guidance by stating that connect_github() should be called first if there's a 409 error. This directly addresses alternatives and setup.

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

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

With no annotations provided, the description carries the full burden. It states that projects are scoped to the caller, which is useful, but it does not explicitly confirm that this is a read-only operation with no side effects. For a simple list tool, the verb 'List' largely conveys behavior, but richer disclosure would be beneficial.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. Every word contributes meaning: 'List' defines the action, 'caller's' defines scope, and 'keelen-saas projects' defines the resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 a simple zero-parameter list operation with an output schema present. The description sufficiently identifies the resource and ownership scope, and the output schema covers return-value details. No additional context is needed for an agent to select and invoke 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?

The tool has zero parameters and the schema is empty, so there are no parameter semantics to elaborate. The description adds no parameter details, but none are needed; the baseline for zero-parameter tools applies.

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

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

The description clearly states the action ('List') and the resource ('the caller's keelen-saas projects'). It is easily distinguished from sibling tools like list_roadmap, list_escalations, and list_github_repos by naming the exact resource type and ownership 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 implies this tool is used to see the caller's projects, but it does not provide explicit when-to-use guidance or mention alternatives. The context is clear enough to infer usage, but no exclusions or comparisons to related list tools are given.

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

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

With no annotations provided, the description carries the full burden. It does not disclose whether the operation is read-only, requires specific permissions, returns paginated results, or any other behavioral traits. The only extra detail is the default status, which is a minor addition.

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

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

The description is a single, front-loaded sentence that states the core purpose immediately. It avoids fluff and is appropriately concise, though it could afford more detail without becoming wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, return values need not be explained, but the description lacks essential context like read-only semantics, availability of filtering, and any assumptions about the project. It is too sparse to fully guide an agent, especially without annotations.

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

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

The schema has 0% description coverage, so the description must compensate. It explains the 'status' parameter's default value but gives no information about 'project_id' or valid status values. This is insufficient for a two-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 clearly states 'List a project's roadmap items' with a specific verb and resource, and it adds context about the default status 'queued'. It distinguishes from sibling tools like cancel_roadmap_item or reorder_roadmap by being a pure list operation, though it doesn't explicitly contrast them.

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

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

The description provides no guidance on when to use this tool versus alternatives like list_project or list_escalations, or when not to use it. It only implies a read-only listing operation without any explicit conditions 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?

With no annotations, the description carries the full burden. It discloses key behaviors: mints a single-use token, returns a deep link, works once, expires in 15 minutes, and that a fresh call is needed for a new link. This is comprehensive and goes beyond a simple 'return a link' statement.

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

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

The description is moderately sized (two short paragraphs) and front-loaded with the core purpose. Each sentence adds meaningful detail (use case, token mechanics, expiration). It is slightly longer than strictly necessary but remains focused and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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-parameter tool, the description is complete. It explains what the tool returns, how it works, the single-use expiration, and the intended action ('Send the user the returned login_url'). No additional context is needed 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?

The tool has zero parameters, so the baseline is 4. No parameter descriptions are needed. The description does mention the output (login_url) and its lifecycle, which indirectly explains what an agent needs to know about the result.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Get a one-click, pre-authenticated dashboard sign-in link for the owner.' The verb 'Get' and the specific resource (dashboard sign-in link) make it unambiguous, and the detailed explanation of the login flow distinguishes it from 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 provides context on when to use it: 'The engine-connect step — and any dashboard task (billing card update, a project page) — needs a signed-in browser.' This clarifies the scenarios requiring the tool, though it does not explicitly mention alternatives or exclusions. The context is strong enough for an agent to decide appropriately.

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

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

With no annotations, the description must carry the burden of disclosing behavior. It explains the glm_peak_paused field's semantics and intent ('an intentional cost gate, not a fault'), which is valuable. However, it does not explicitly state that the operation is read-only, though 'get' strongly implies it. Overall, good transparency but not exhaustive.

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

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

The description is a single dense sentence that lists metrics and includes a parenthetical explanation. It is efficient with no wasted words, though it could be structured with line breaks or bullet points for better readability. It remains appropriately sized for the content.

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

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

Given the tool's simplicity (one parameter) and the presence of an output schema, the description covers the main metrics and explains the special glm_peak_paused case. It is sufficiently complete for an agent to understand what the tool returns and how to interpret the fields.

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

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

The schema has one parameter, project_id, with no description (0% coverage). The description does not elaborate on what project_id is or how to obtain it, beyond the implied meaning from the tool name. It could have added context like 'the ID of the project to query,' but it does not, leaving the agent to infer from the name.

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

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

The description clearly states 'Get a project's lifecycle status' and enumerates specific metrics, making it a specific verb+resource statement. It distinguishes itself from other get_* tools by focusing on project health indicators like task count, pass rate, and pause state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 this tool—whenever project status details are needed—but does not explicitly mention alternatives or exclusions. The specific metrics imply its use case, though it could benefit from an explicit 'when not to use' statement.

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?

No annotations are provided, so the description carries the burden. It clearly states side effects (moves thread to refine_pending), constraints (status must be 'done', feedback length 1-2000 chars), and next steps (poll get_request_status). This is strong behavioral disclosure beyond just stating the operation.

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

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

Three short sentences, each with a distinct piece of information: operation+limitation, requirements, and side effects/next step. No fluff, 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?

Given the tool's moderate complexity (mutation, state change, polling behavior), the description thoroughly covers operation, preconditions, side effects, and next steps. Slight gap: no explicit mention of what happens on failure or how to handle the 'max 5x' limit beyond 'max 5x'.

Complex tools with many parameters or behaviors need more documentation. 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 explain the parameters. It explains feedback_md's purpose and length constraint but does not detail project_id or thread_id, though those are self-explanatory and standard. The description adds meaning to feedback_md but omits some detail on the IDs.

Input schemas describe structure but not intent. Descriptions should explain 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 the tool refines roadmap items from a done thread with feedback, specifying the resource (roadmap items), action (refine with feedback), and constraint (max 5x). It is clear but could better differentiate from siblings, though the action is specific enough to stand out.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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: when the status is 'done', and provides instructions to poll for revised items via get_request_status. It does not explicitly mention alternatives or when not to use it, but the context is sufficient for an agent to know 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?

The description discloses key behaviors: priority ordering, pinned item handling, unknown IDs skipped, duplicates rejected, and the return object. Given no annotations, it covers essential side effects and output format.

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

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

The description is thorough but not overly verbose. It is structured into clear sentences explaining the order and exceptions. No redundant 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?

It covers the purpose, parameter semantics, return value, and edge cases. There are no annotations, so this description carries the full load; it is sufficient for basic usage, though error handling is omitted.

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

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

It provides meaningful semantics for ordered_ids (desired order, first is highest priority) and mentions project_id implicitly. The schema only lists types, so the description adds necessary 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 clearly states the tool's purpose: reprioritizing queued roadmap items. It specifies the ordering behavior and differentiates from sibling tools like list_roadmap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 implies usage by referencing list_roadmap for obtaining IDs and explains edge cases with pinned items. However, it does not explicitly contrast with other mutating tools or state 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?

No annotations are provided, so the description carries full responsibility. It discloses idempotency, the audit trail append, the conditional resume behavior, and accepted ID formats — comprehensive and unambiguous.

Agents need to know what a tool does to the 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 tactically composed in three sentences: purpose, behavioral logic, and ID format. Every sentence adds distinct value with no redundancy.

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

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

Given the existence of an output schema and the moderate parameter count, the description is complete. It covers side effects, idempotency, parameter variants, and conditional behavior, leaving little to guess.

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

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

Schema description coverage is 0%, but the description fully remedies this: it explains decision_md is a required short reason note appended for auditing, and clarifies escalation_id accepts real UUIDs or synthetic orphan:<project_id> ids. Both parameters are given meaningful semantics beyond the schema.

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

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

The description uses a specific verb ('Mark an escalation handled') with a clear resource (escalation queue) and distinguishes itself from sibling list_escalations. It also details type-specific behavior with project_pause/orphan_pause vs task_block/operator_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?

The description clearly allows invocation with a real escalation UUID or synthetic orphan id, and explains when it resumes a project vs acknowledges a task. It does not explicitly exclude alternatives, but the context is strong enough for appropriate 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?

With no annotations provided, the description carries full weight and does so well: it discloses that a NEW Roblox version is minted, that the retained artifact is used, and that certain conditions produce 404, 422, 409, or 403 responses. This substantially exceeds the structured metadata.

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

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

The description is a single focused paragraph with no filler. Every sentence adds behavioral, error, or usage information, and the most important action is stated first.

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

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

For a two-parameter mutation tool with an output schema, this description covers the workflow, the source of version numbers, error semantics, side effects, and the return shape. Nothing essential is left unexplained.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify `version_number` (a previously published version drawn from the Roblox Publishing card) and the behaviors around retained artifacts, but it leaves `project_id` mostly implicit. Still helpful and materially 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 uses a specific verb ("roll back") with a clear resource (a Roblox place) and adds precise mechanics: it re-publishes the RETAINED build artifact for a given version rather than rebuilding. This is unambiguous and distinct from any sibling tool.

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

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

It explicitly scopes the tool to `roblox_game` projects, explains the rollback mechanism is fast/deterministic because it never rebuilds from source, and tells the user where to obtain valid version numbers. Error statuses also provide practical guidance for when the operation is not applicable.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It comprehensively covers side effects (records observations, makes no changes), non-deterministic outcomes (does not determine standing), mandatory user interaction (disclaimer_md must be repeated), billing implications, concurrency limits (one in flight per project), and error behavior (refusals return ok:false with next step). It also mentions rate limits. This is a thorough and transparent disclosure for a mutation-like tool.

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

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

The description is well-structured and efficient. It opens with the core purpose in one sentence, then expands into behavioral notes, prerequisites, and operational constraints in a logical order. Every sentence adds new information—no fluff or repetition. The front-loading ensures the primary action is immediately clear, while additional details are presented in digestible chunks.

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

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

Given the tool's complexity (multiple frameworks, prerequisites, billing, concurrency, rate limits, disclaimer requirement), the description covers all essential context for an agent to decide whether to invoke it. It explains the operational environment, what the tool does and does not do, and the exact failure response. An output schema exists, so return-value details are not required, and the description does not overcommit. The inclusion of the disclaimer_md requirement is a critical interaction detail that is fully specified.

Complex tools with many parameters or behaviors need more documentation. 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 not explicitly define project_id, but the description makes clear the parameter refers to the project for which the review is run, and it adds meaningful constraints: the project must have a saved framework profile, an eligible plan, and operator allowlist access. This context goes beyond the schema's bare 'Project Id' title and helps the agent understand the prerequisite eligibility for the parameter.

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

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

The description states a specific action: 'Start a source-bound security control gap review for one project.' The verb 'Start' with the resource 'security control gap review' clearly defines the tool's purpose, and the scoping to 'one project' plus the framework context (Cyber Essentials, CMMC) distinguishes it from siblings like run_legal_exposure_review and run_security_review, which cover different review types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 by listing prerequisites (saved framework profile, eligible plan, operator allowlist) and constraints (billable, one in flight per project, rate-limited). It also clarifies what it does not do (determine framework standing, make changes) and describes refusal behavior. However, it does not explicitly name alternative tools or state when-not-to-use beyond implied scope, falling short of the 5-level bar for explicit exclusions and alternatives.

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

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

No annotations are provided, so the description carries full disclosure burden. It explicitly states this is a one-shot review machine that reads offline, maps code to legal obligations, and does NOT apply changes automatically. It discloses the disclaimer field requirement, non-exhaustiveness, refusal behavior (409-shaped, ok:false with next_step), and rate limiting. This is exceptionally transparent for a mutation-like operation.

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

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

The description is a single paragraph with a few sentences, but it contains substantial, well-organized content. It front-loads the primary purpose, then covers secondary behaviors and requirements. It's not overly long and every sentence adds value. It could be slightly more structured with bullet points, but it's readable and 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 there is an output schema (implied by 'has output schema: true'), the description doesn't need to list return fields, but it mentions the disclaimer_md field and the ok:false structure for refusals. It covers prerequisites, side effects (findings on Legal page), non-exhaustiveness, and rate limits. For a tool with one parameter and clear annotations absent, it is remarkably 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?

There is exactly one parameter (project_id) with 0% schema description coverage. The description does not elaborate on the parameter beyond its existence, but since there is only one parameter with a clear name (project_id) and the description mentions 'a project's repository', the meaning is evident. The description could benefit from explaining the format or expectations, but given it's a single obvious parameter, a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Start a legal exposure review') and clearly identifies the resource ('a project's repository'). It distinguishes itself from siblings by noting the offline checkout, compliance profile filtering, and where findings land (Legal page). It could be mistaken for run_control_gap_review or run_security_review, but the description's focus on legal compliance and the mention of get_legal_exposure_findings (a sibling) sets it apart.

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

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

The description implicitly explains when to use it: when you need a legal review of a repository. It also provides explicit prerequisites (saved compliance profile, a plan, operator allowlist) and mentions rate limits. It doesn't explicitly say when NOT to use it or name alternatives, but the mention of sibling tools and the context of compliance makes it clear. The disclaimers about non-exhaustiveness and non-legal-advice further guide appropriate 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?

With no annotations, the description carries full burden and does so thoroughly: it is billable, no fixes are applied automatically, findings are posted for human triage, concurrent audits are limited, allowlisted projects only trigger, and unpaid workspaces just get an upgrade message. It also describes the scan taxonomy and where results go.

Agents need to know what a tool does to the 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 main purpose is front-loaded and every sentence adds operational information. It is dense, with long parentheticals and a taxonomy list, but no filler; the bulk is necessary context for an agent deciding whether and how to invoke 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?

For a one-parameter tool with an output schema and no annotations, the description covers purpose, scope, workflow, billing, concurrency, allowlist gating, and plan requirements. There are no significant gaps that would prevent correct selection or invocation.

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

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

There is only one parameter (project_id) and the description ties it to the target project ('review of a project'). Schema coverage is 0%, but the single obvious string parameter needs little elaboration; the description compensates by making the target project clear, though it doesn't state ID format or ownership constraints.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Kick off a deep, whole-repo security review of a project.' It clearly distinguishes run_security_review from sibling audit tools like run_control_gap_review and run_legal_exposure_review by naming the security taxonomy (secrets, deps, injection, SSRF, etc.) and the project-scoped target.

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

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

It gives clear context for invoking: paid plan required, one audit in flight per project, and disabled unless on operator allowlist. It does not explicitly name alternatives, but the security-specific scope plus the 'one-shot audit' and human-triage workflow make when-to-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?

With no annotations, the description covers essential behavior: mutation (set), the non-empty constraint on goal_md, tenant scoping (404 if not in workspace), and the return payload. It doesn't mention idempotency or permissions, but is reasonably transparent for a simple setter.

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

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

The description is exceptionally concise—two sentences that front-load the purpose, then cover constraints and return format. Every sentence earns its place with no redundancy.

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

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

For a tool with only 2 params and an output schema, the description covers purpose, constraints, error condition, and return. It could mention whether the goal is overwritten (implied by 'set') and any authorization requirements, but these are minor gaps for a simple setter.

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

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

With 0% schema description coverage, the description compensates by explaining that goal_md is free-form markdown and must be non-empty, and that project_id is tenant-scoped (404 if not in workspace). This adds meaningful context beyond the bare schema types and required flags.

Input schemas describe structure but not intent. Descriptions should explain 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: 'Set a project's product goal' and specifies the effect ('prepended to PM/dev/QA iter prompts'). This verb+resource formulation is specific and distinguishes it from sibling tool set_product_vision, which targets a different type of goal.

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

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

The description provides situational context (prepending to iter prompts, tenant scoping) but lacks explicit guidance on when to use this vs. alternatives like set_product_vision. It implies usage but does not state exclusions or comparisons.

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

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

With zero annotations, the description carries the full transparency burden and delivers: side effects (prepended to agent prompts), validation (vision_md non-empty), auth failure mode (404 for out-of-workspace projects), and return contract. This dramatically exceeds what 'update' style descriptions provide and gives an agent operational expectations without requiring a call to find out.

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

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

Every sentence earns its place: one topic sentence establishing purpose, followed by a compact paragraph covering validation, auth scoping, and return value. Zero wasted words while conveying roughly four distinct behavioral facts.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 moderate-complexity mutation (2 params, no enums, no nesting, has output schema), the description covers side effects, error cases, validation, and return shape. The provided context signals show no enums or nested objects needing elaboration, and the output schema removes the need to describe return values in prose. Minor gap: doesn't clarify whether setting is a replace or merge operation, or any length limits on the markdown.

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

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

At 0% schema coverage, the description must compensate and does: vision_md is specified as free-form markdown with a non-empty constraint. The tenant-scoping note adds meaning to how project_id is validated. However, project_id itself is only implicitly understood from its name, with no description of the ID format or where to find it. Strong for vision_md, slightly thinner for project_id.

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

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

Crystal-clear verb+resource: 'Set a project's product vision' with additional scoping details (prepended to iter prompts, tenant-scoping). The description adds meaningful behavior (404 behavior, return shape) that fully disambiguates it from siblings like set_product_goal, which differ in the resource being set. No ambiguity about what this tool does.

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

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

Provides clear contextual guidance by explaining the side effect ('prepended to PM/dev/QA iter prompts'), which tells an agent why it would set this vs. read it, and the tenant-scoping constraint. However, it stops short of explicitly naming alternatives or stating when-not-to-use (e.g., no explicit contrast with set_product_goal or create_project).

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

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

With no annotations provided, the description fully carries behavioral disclosure. It reveals email delivery, 15-minute expiry, enumeration-safe uniform responses, rate limiting per IP/email, and the potentially serious consequence that a guessed address signs the user into an unintended account. It also explains that the call is safe to reuse for resending.

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

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

The description is long but every sentence earns its place given the sensitive dual signup/login behavior. It front-loads the core action, then gives the precise flow, then security caveats. The structure uses paragraphs and arrows effectively 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?

The description covers prerequisites, sequencing, parameters, error/reuse behavior, security side effects, and the follow-up tool to continue setup. An output schema exists, so explaining return values is not required. The tool is complex and the description is thorough enough 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?

Although the schema only lists email as a required string, the description adds essential meaning: email is the destination for the code, must be obtained by asking the user, must not be inferred from any ambient source, and has security implications because signup acts as login. 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 opens with a specific verb and resource: 'Create a Keelen account (or start agent login) — emails a 6-digit code.' It clearly distinguishes itself from siblings like verify_email by outlining the signup flow, and clarifies that signing up doubles as agent login.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 this tool: it is 'UNAUTHENTICATED' and 'the only tool besides verify_email that works before a bearer key is configured.' It also gives a full invocation flow with verify_email, tells the agent to prompt the user for email and wait, warns against inferring email from ambient sources, and explains that signup can resend codes.

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

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

With no annotations provided, the description carries the burden of disclosure. It reveals that submission is asynchronous by returning {thread_id, status, next_action, poll_after_seconds, next_step} and instructs re-checking status. It does not explicitly state that a project must exist or whether the submission is reversible, but the core behavioral flow is well explained.

Agents need to know what a tool does to the 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: a single-purpose summary followed by concise, high-value operational instructions. Every sentence earns its place, including the size limit, batching rule, and return-field follow-up guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, return values are largely self-documenting, and the description focuses on what structured fields miss: async behavior, the remaining policy constraints, and the next-step workflow. With sibling tools in view, it fully equips an agent to call this tool and correctly chain into get_request_status.

Complex tools with many parameters or behaviors need more documentation. 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 0% description coverage, so the description must add meaning. It explains the 'text' parameter's constraints and batch usage, and 'project_id' is implied as the target project. It does not elaborate on project_id format or validation, but the combination of schema names and description covers the essential semantics for correct invocation.

Input schemas describe structure but not intent. Descriptions should explain 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 specific language ('Submit a free-form Roadmap Request to a project (enters PM intake)') that clearly identifies the action, resource, and destination. It distinguishes itself from siblings like get_request_status, answer_request, and refine_request by focusing on the initial submission 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?

Explicit usage guidance is provided: 'Submit ONE feature or intent per call; split a multi-feature ask into separate requests.' It also gives a concrete limit ('text must be under 16000 characters') and directs the agent to follow up via get_request_status after the specified polling interval.

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?

No annotations are provided, so the description carries full burden. It discloses unauthenticated access, time/attempt limits, reveal-once behavior, and security requirements (store only in MCP client config). This goes beyond just 'verifies email' to explain exactly what happens and how to handle the result.

Agents need to know what a tool does to the 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 but information-dense, using clear sections. Every sentence serves a purpose: action, conditions, security, and next steps. Front-loaded with the core action and follows with critical details, no 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?

Given the sensitive nature (reveal-once API key), the description covers everything: purpose, prerequisites, constraints, error handling, and post-conditions. Even without an output schema (though one exists), the description explains the key's one-time visibility and how to use it, making it 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 must compensate. It explains 'email' and 'code' in context: email must match signup, code is the 6-digit code. It doesn't detail format (e.g., email validation) but adds critical meaning about their relationship and constraints, which is valuable.

Input schemas describe structure but not intent. Descriptions should explain 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 redeems an emailed code for an API key, with the verb 'Redeem' and specific resource. It distinguishes from siblings like signup by focusing on code redemption, and from get_onboarding_status by noting the reconnect-and-call flow.

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

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

Explicitly states when to use: after signup(email), within 15 minutes, with a 5-attempt max. It provides a clear sequence (store key, reconnect, call get_onboarding_status) and error handling (call signup for fresh code). Also warns not to use for other purposes by specifying constraints.

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