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

Annotations already mark destructiveHint=true and readOnlyHint=false, but the description adds concrete side effects: opens a GitHub PR, replaces env vars in the repo, shifts production/preview behavior, and creates platform-specific jobs. Also discloses deprecated aliases and platform gating, providing far more behavioral context than the structured fields alone.

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

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

Front-loaded with the purpose and trigger condition, then organizes the four choices into numbered items and platform-specific details into bullets. Though lengthy, every sentence carries essential operational detail for a branching, destructive tool; no filler or redundancy.

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

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

Covers trigger, mandatory user-consent step, all choice semantics, method mapping, historical compatibility, and platform-specific job creation. Output schema is present, so omission of return-value detail is acceptable. Nothing needed to call the tool correctly is missing.

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

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

Schema coverage is 100%, but the description goes beyond the schema by explaining each `choice` literal, its corresponding `method`, the resulting deployment behavior, and deprecation notes. It also clarifies platform-specific behavior under method='auto', enriching parameter meaning substantially.

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

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

States a specific verb and resource: choose how to handle backend switchover in Phase 7. Differentiates from sibling choose_* tools (choose_data_import_method, choose_frontend_deploy) by naming the backend switchover phase explicitly and enumerating the four choice values.

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 trigger condition: 'Call when MANUAL_CHOOSE_BACKEND_SWITCHOVER is READY.' Mandates user interaction: 'You MUST present these options to the user and ask them to choose before calling.' Describes when method='auto' vs 'skip' applies and platform-specific job creation, leaving no ambiguity about when to invoke.

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

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

Goes well beyond the annotations by disclosing important behavior: if the gate closed in the meantime, the call returns ok when the method matches and HTTP 409 when it differs; the choice cannot be changed; and the agent should re-fetch the migration instead of retrying. This is valuable runtime behavior not inferable from readOnlyHint/destructiveHint alone.

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

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

Front-loaded with purpose and trigger, then structured around numbered options and a clear prohibition. The longer second half covers conflict behavior, which is essential context. Every sentence earns its place and there is no filler or restating of the name.

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

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

Covers the trigger, the user-interaction requirement, the alternative auto-selection path, the exact pendingAction condition, and the closed-gate conflict behavior. Together with the output schema and 100% parameter coverage, nothing needed to call this tool correctly is missing.

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

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

Schema coverage is 100% and the description adds meaning to the 'method' parameter by explaining what 'automated' and 'manual' actually entail. It also clarifies that jobId is the MANUAL_CHOOSE_DATA_IMPORT_METHOD job ID. Only migrationId leans on the schema, which is acceptable given full 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 specific action ('Choose how to import data in Phase 3') and the exact trigger condition (MANUAL_CHOOSE_DATA_IMPORT_METHOD job READY with pendingAction.type CHOOSE_DATA_IMPORT_METHOD). This also differentiates it from siblings like choose_backend_switchover and choose_frontend_deploy by tying it to Phase 3 and the import gate.

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?

Very explicit: it must be called only when the MANUAL_CHOOSE_DATA_IMPORT_METHOD job is READY, and only when pendingAction.type is CHOOSE_DATA_IMPORT_METHOD. It also states when NOT to call it (when PROBE_SOURCE already deployed and verified, Staticbot auto-selects automated), and requires asking the user before choosing. No ambiguity remains.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to restate mutability. It adds important behavioral context: the tool requires user consent before execution, and for staticbot it may select a target automatically, so the agent must not make premature promises. These details go beyond the schema and annotations.

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

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

The description is moderately long but well-structured: it leads with the trigger condition and the critical user-consent requirement, then enumerates the three options in a clear list. Each sentence serves a purpose—no fluff. The warning about staticbot analysis is concise and essential.

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 trigger, the required user interaction, the three choices with their parameters, and a specific caution about staticbot. Since an output schema exists (context signal: has output schema true), return value details are not needed. It omits nothing an agent needs to correctly invoke this tool in its workflow.

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

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

Schema coverage is 100% with descriptions for all four parameters, so baseline is 3. The description adds meaning by mapping method values to the corresponding choice values (e.g., 'continuous-sync' → 'setup-continuous-sync') and clarifying that skip requires no choice. This explains the relationship between method and choice, which the schema alone does not.

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: choosing frontend deployment strategy in Phase 8. It names the three distinct options (continuous-sync, staticbot, skip) and explains what each does, clearly distinguishing from sibling tools like choose_backend_switchover which handles a different phase. The verb 'choose' plus resource 'frontend deployment' makes it unambiguous.

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

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

It explicitly specifies when to call: when MANUAL_CHOOSE_FRONTEND_DEPLOY is READY, and mandates user interaction ('MUST present these options... Do NOT pick without asking'). It does not name alternatives, but the context of a phase-based workflow makes it clear this is the right tool for this step. The instruction to not promise AWS/Cloudflare before staticbot analysis is also a usage guideline.

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

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

Although the destructiveHint annotation already signals mutation, the description goes much further: it enumerates exactly what DATABASE, STORAGE, and PROJECT scopes delete and preserve, and states that the operation cannot be undone. This substantially exceeds the annotation's binary signal and gives the agent the full safety picture.

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 detailed for a destructive irreversible operation and every sentence serves a purpose: defining scopes, stating the prerequisite plan call, mandating confirmation, and noting post-state. It is structured by scope type for easy parsing, with the most critical warning front-loaded.

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

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

Given the tool's destructive nature, the description fully covers prerequisites, per-scope effects, irreversibility, required user confirmation, and the post-cleanup state. The presence of an output schema means return-value details do not need to be repeated. Nothing needed to call this tool safely is missing.

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

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

The schema already documents all three parameters, so the baseline is high. The description still adds meaning by explaining where confirmProjectRef comes from, requiring that it be copied rather than guessed, and tying the scope parameter to the exact scope the user approved. This is genuinely useful beyond the schema's field-level descriptions.

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

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

The description opens with a specific verb and resource: 'Destructively clean conflicting objects from a Supabase Cloud migration target.' It clearly distinguishes this tool from get_clean_target_plan by framing it as the destructive execution step that follows the planning call.

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

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

The description explicitly instructs the agent to call get_clean_target_plan first, retrieve confirmProjectRef from its response, and obtain explicit user confirmation before proceeding. It also specifies exact scope consequences and even notes that the migration remains paused after cleanup, giving the agent a clear execution protocol.

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

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

Beyond the annotations, the description discloses important side effects and edge-case behavior: calling it on an already-completed sync step returns ok, completing a MANUAL_REVIEW_SCHEMA job without approvedSql leaves the dependent APPLY_SQL job with nothing to apply, and Staticbot auto-completes sync steps within about 15 seconds. This goes well beyond the readOnlyHint/destructiveHint annotations and helps the agent reason about outcomes.

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

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

The description is dense and front-loaded with the core purpose, and every sentence carries useful information. It is somewhat long and runs together as one paragraph, but the complexity of the tool justifies the length. Minor restructuring into explicit scenarios would improve scannability, but there is 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 tool's complexity, the description covers prerequisites (READY status), per-job-type behavior, automatic completion alternatives, exact function URL format, and the consequence of omitting approvedSql. With an output schema present and 100% parameter coverage, an agent has everything needed to decide whether and how to call the tool correctly.

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

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

Although the schema already covers all parameters, the description adds substantial meaning: it explains the functionUrl format (https://{projectRef}.supabase.co/functions/v1/{functionName}), clarifies that functionUrl is required for MANUAL_SYNC_LOVABLE but omitted for MANUAL_SYNC_BASE44, and elaborates on approvedSql being injected into the dependent APPLY_SQL job. These details go beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: 'Complete a manual job that requires user action.' It then names the exact job types it applies to (MANUAL_SYNC_LOVABLE, MANUAL_SYNC_BASE44, MANUAL_EXPORT_DATA, MANUAL_IMPORT_DATA, etc.), making its scope unambiguous. This clearly distinguishes it from sibling tools like retry_migration_job or skip_migration_job.

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 exceptionally clear when-to-use guidance: for sync jobs it explicitly says the tool is normally NOT needed, tells the agent to ask the user to paste a command, and specifies to poll get_migration or call validate_function_url instead. It also states the precise condition for using this tool ('only when the function URL differs from the one in the job's inputData') and gives step-by-step handling for MANUAL_REVIEW_SCHEMA.

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

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

Beyond the annotations, it mandates explicit user choice, forbids inferring gateChoice, forbids bypassing REVIEW_TARGET_CONFLICTS without discussion, and documents the omit-to-use-newest behavior for gateSelection. This is strong disclosure of the tool's decision-making and consent requirements.

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

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

The description is dense but well ordered: purpose first, then workflow, parameter-specific rules, and a final guardrail. Every sentence carries an operational requirement, and none is wasted on boilerplate.

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

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

For a destructive confirmation gate with conditional behavior, the description covers prerequisites, exact pre-flight handling, default selection behavior, and a hard fail-safe rule. It references the relevant get_migration fields and relies on the detailed schema and output schema for the remainder, leaving no critical invocation gap.

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

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

The input schema already describes all three parameters at 100% coverage, including the exact source of gateChoice and the USE_OFFICIAL_EXPORT semantics of gateSelection. The description mostly restates those rules in prose rather than adding new parameter-level detail.

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

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

The opening sentence specifies two concrete modes: approving a migration after discovery and resolving a pre-flight migration-strategy gate. This makes the action unambiguous and distinguishes it from read-only or lifecycle siblings such as get_migration, resume_migration, and pause_migration.

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 an explicit precondition and workflow: get the migration, present the discovery inventory, and if preFlightGate is non-null present each action verbatim and pass the exact gateChoice. It does not explicitly name sibling-tool alternatives or when not to use them, but the conditional triggers are clear.

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

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

Beyond the annotations, the description discloses major behavioral consequences: skipDestructive is permanent, skipped migrations are never re-applied, the run still completes, divergence is unreported, and the API returns 400 without acknowledged=true. This is exactly the kind of hidden behavioral context an agent needs.

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

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

The description is long but every sentence carries essential safety information. It front-loads the core purpose and then layers necessary warnings. No filler or redundant restatements of the schema.

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

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

Given the tool's destructive potential, the description is complete: it covers the exact trigger state, the optional destructive-skip path, the permanence warning, the acknowledgement requirement, and the error behavior. An output schema exists, so return-value details are appropriately 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?

Although schema coverage is 100%, the description adds critical semantics beyond the schema: it explains that acknowledged must only be set after the user explicitly sees and approves the permanent consequence, and it expands on skipDestructive's permanent, non-deferral nature. This materially improves parameter understanding.

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: "Confirm a sync run that is PAUSED_FOR_REVIEW." It also clarifies the optional skip behavior, making it easy to distinguish from related sync/migration 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 clearly states when to use the tool: for sync runs paused due to destructive migrations. It also gives a strong when-not instruction: "Never set acknowledged just to clear the error." However, it does not explicitly name alternative tools such as retry_sync_run or skip_sync_run for handling other sync states.

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

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

Beyond the annotations (which only say readOnly=false and destructiveHint=false), the description discloses critical behavior: the deployment is prepared but not started, APPLY creates real infrastructure, and targetAccountId determines infrastructure ownership. It also adds strong guardrails such as 'Never invent an account id or send infrastructureOwnership' and the consequence of omitting Cloudflare fields.

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

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

The description is information-dense but well organized: first the core behavior and default, then the AWS workflow, then the Cloudflare workflow. Every sentence adds decision-relevant guidance, and the key 'does NOT start it' distinction is front-loaded.

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

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

For a fairly complex tool with 5 parameters, the description covers the main flow, the AWS-specific prerequisite, the Cloudflare-specific conditional flow, and the normal default. The output schema exists, so return-value details are already covered. An agent has enough context to invoke this tool correctly in all the described scenarios.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful workflow context beyond the schema: it explains that targetAccountId must be the exact `value` from list_aws_hosting_targets, that it decides infrastructure ownership, and that cloudflareChoice/cloudflareHostname should be omitted for the normal existing-hosting path. This raises it above 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 states a specific verb and resource ('Create a new deployment for a stack') and immediately distinguishes itself from the sibling start_deployment by clarifying that this tool only prepares the deployment. It also clarifies the deployment type semantics (APPLY vs PLAN), making the tool's 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 gives explicit when-to-use guidance: call start_deployment next, use PLAN for dry-run preview, call list_aws_hosting_targets first for AWS-hosted stacks, and call list_cloudflare_hosting_targets + preflight_cloudflare_hosting for customer-owned Cloudflare apps. It also explicitly says when NOT to set Cloudflare fields, which is the normal case.

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

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

Annotations only say readOnlyHint=false, openWorldHint=false, destructiveHint=false, which is minimal. The description compensates by disclosing the multi-phase pipeline, the pause after DISCOVERY (PAUSED_FOR_APPROVAL), the requirement that source and target Supabase projects must differ, and the fact that FIREBASE cannot be created through this connection. It also warns that secret-looking configOverrides keys are REJECTED, not ignored. It does not explicitly state that the tool is non-destructive, but the annotations already cover that; the description adds substantial behavioral context beyond the annotations.

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

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

The description is long, but every section earns its place: the pipeline overview, delivery modes, source platform matrix, pre-call workflow, and post-creation behavior are all necessary for correct invocation. The numbered steps and bolded mode names make it scannable. It loses one point because the length is substantial and some information (e.g., the full pipeline list) could be condensed without losing meaning, but it is well-structured and front-loaded with the most important 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?

Given the tool's complexity (14 parameters, 5 source types, 2 target modes, multi-phase pipeline), the description is remarkably complete. It covers prerequisites, parameter sourcing, error/stop conditions, the FIREBASE exclusion, the source/target project difference validation, and the post-creation pause. The output schema exists, so return values need not be described. An agent has everything needed to invoke this tool correctly and to route the user appropriately.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains when to omit target* params (SUPABASE_SELF_HOSTED), when base44AppId is required and why (a Base44 token covers every app in the workspace), and when sourceDeployedUrl is needed (legacy BASE44_SUPABASE with placeholders). It also clarifies that templateId is required for every source type reachable from here, which is not obvious from the schema alone. This pushes it above 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 opens with a clear verb and resource ('Create a new migration') and immediately distinguishes the tool from siblings by outlining the multi-phase pipeline and the two delivery modes. It also names the source platforms it supports and explicitly says FIREBASE is NOT creatable through this connection, which prevents a wrong invocation. This is a specific, well-scoped definition that an agent can act on without ambiguity.

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 an explicit, numbered pre-call workflow: call get_account_status first, stop if pendingAction is CONNECT_SOURCE_CONTROL or CONNECT_DATABASE, use list_source_repositories before asking for a repository URL, and choose between SUPABASE_CLOUD and SUPABASE_SELF_HOSTED. It also names alternatives (list_supabase_projects, list_supabase_organizations, create_supabase_project, list_templates, create_template) and gives clear conditions for when to use each. This is exemplary usage guidance.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is not a read-only operation. The description adds value by explaining what actually happens when called: it builds the migrated app on Staticbot's infrastructure. It also discloses a dual trigger-or-retrieve behavior, which is useful context beyond the annotations.

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

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

Three sentences, no wasted words, with the core action front-loaded. Every sentence contributes: what the tool does, why it exists, and how the mode parameter behaves. The structure is clear and easily parseable.

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

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

An output schema exists, so return values do not need to be explained. The description covers the trigger/retrieve distinction, the build purpose, and mode options, which is sufficient for a two-parameter tool. It could slightly improve by explicitly contrasting with get_migration_deployments, but nothing critical is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description adds meaningful extra semantics for 'mode' by defining what 'light' means (fast, single SOFTWARE job) and indicating the default behavior. This goes beyond the schema's minimal enum listing and helps agents choose a mode.

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

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

States a specific action ('Trigger (or retrieve)') on a specific resource ('a preview deployment for a migration'), making the tool's role immediately clear. The mention of building the app on Staticbot's infrastructure further distinguishes it from generic deployment or migration tools. It reads unambiguously as the preview step before backend switchover.

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 places the tool in a clear workflow context: verify the migrated app works before finalising backend switchover. This implies the appropriate timing relative to sibling tools like choose_backend_switchover, though it does not explicitly name alternatives or state when not to use it. The guidance is implied but strong enough for an agent to infer correct placement.

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

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

Annotations are sparse (readOnlyHint=false, openWorldHint=false, destructiveHint=false), so the description carries the full burden. It richly discloses behavior: Staticbot owns the hosting decision, routing static to AWS and SSR/full-stack to Cloudflare Workers. It explains the output fields ('hostingWorkload', 'deploymentTarget', 'infrastructureOwnership') that the agent should report. It also warns about secret rejection: 'secret-looking keys are REJECTED, not ignored' and explains Supabase auto-refresh behavior. This goes well beyond annotations.

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

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

The description is excessively long (over 300 words) for a tool with already-detailed schema. It repeats information already in the schema (e.g., the cloudflareChoice description essentially duplicates the property description) and includes procedural narrative that could be shortened. It is not front-loaded effectively; the core purpose is stated first, but the subsequent paragraphs are dense and could be condensed. This is over-specification, not concise 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 tool's complexity (7 params, nested objects, multiple hosting targets, security constraints), the description provides comprehensive context: prerequisites (list_templates), provider selection rules, credential handling, and expected outputs. With an output schema present (has_output_schema=true), the return value explanation is not required. The description covers all necessary aspects for an agent to call it correctly.

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

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

Schema description coverage is 100% (as indicated by the signal), and the schema already provides descriptions for all 7 parameters, including nested objects and special constraints. The description adds value by specifying relationships between parameters (e.g., 'supabaseIntegrationInstanceId must be set with supabaseProjectRef') and clarifications for cloudflareChoice (pass only after preflight). However, since the schema already covers the basics, the description's incremental semantics are moderate, justifying a 3.

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

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

The description states a specific verb ('create'), a specific resource ('infrastructure stack'), and the purpose ('ties a template to a domain and becomes deployable'). It clearly differentiates from siblings like list_stacks, get_stack, and create_deployment. The mention of 'from a template' and 'deployable' adds precise context.

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

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

The description explicitly directs when to use this tool: 'Call list_templates first to find the right templateId'. It also names alternatives for related decisions: 'call list_cloudflare_hosting_targets' for Cloudflare, 'call list_aws_hosting_targets' for AWS, and notes that there is no AWS account field on create_stack. It clearly states what not to do ('Never invent a provider or an account') and when to omit optional parameters ('Omit it for Staticbot hosting').

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description goes far beyond, explaining that it changes an external account, consumes a project slot, affects billing, and that the password is intentionally never returned. It also discloses asynchronous provisioning behavior and the polling requirement. No contradiction with annotations.

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

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

The description is compact and front-loaded with the most critical facts: external impact, prerequisites, and confirmation. Every sentence provides essential operational guidance, with no fluff or redundancy.

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

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

Given the tool's complexity (external side effects, async provisioning, secrets handling), the description covers everything an agent needs: prerequisites, confirmation, password behavior, polling instructions, and anti-repeated calls. The output schema exists, but the description still clarifies the async flow.

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

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

Schema coverage is 100% with each parameter having a description. The description adds value by emphasizing that the name, organizationId, and region must be exactly what the user confirmed and selected from the list tools, and that supabaseIntegrationInstanceId comes from list_integration_instances. This is beyond the schema's basic descriptions.

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

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

The description clearly states the tool creates a new Supabase project in the customer's selected organization, distinguishing it from related tools like list_supabase_projects and get_supabase_project_status. It specifies the resource (Supabase organization) and the action (create project with specific parameters like name, organization, and region).

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

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

The description explicitly instructs when to use this tool, listing prerequisites (list_supabase_organizations and list_supabase_regions) and requiring user confirmation. It also explicitly says when NOT to use it again, advising to poll status instead. This is exemplary guidance.

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

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

Annotations only set readOnlyHint=false, openWorldHint=false, destructiveHint=false, which convey little beyond 'not read-only'. The description carries the full burden and does so thoroughly: it clarifies that creating a template does not commit the user to a migration, that both public and private repos are supported, that omitting sourceControlIntegrationInstanceId can make a private repo look missing, and that the tool classifies hosting workload rather than relying on agent heuristics. No contradiction with annotations.

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

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

The description is long but every sentence earns its place. It front-loads the core purpose and then progressively covers integration prerequisites, common mistakes, and strategic context. There is no fluff or repetition; the length is justified by the tool's complexity.

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

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

Given the tool's complexity (private/public repo handling, multi-account tokens, classification behavior, dual purpose for hosting and migration) and that an output schema exists, the description is fully complete. It covers all critical preconditions, error handling (no integration connected), and non-obvious behavioral aspects, leaving no ambiguity for an agent.

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 already describes all three parameters (100% coverage), the description adds significant meaning: it explains how repoLink should be resolved, why sourceControlIntegrationInstanceId is critical for multi-account setups, and that name is optional and derived from the repo name. This goes well beyond the schema's basic descriptions and materially improves an agent's ability to use the parameters correctly.

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 new template by scanning a source repository, and distinguishes it from list_templates by specifying when to use it ('Use it when no existing template from list_templates matches the repo'). The verb, resource, and scope are specific and unique among siblings.

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

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

Explicitly instructs when to use this tool (no matching template exists), when not to (when a template matches), and names the alternative tool (list_templates). It also provides detailed pre-call steps: resolve the repository via list_source_repositories, pass the integrationInstanceId, and handle the case of no connected integration. This is exemplary usage guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses time-limited presigned URLs, that the password is shown only here and never logged, and the premature-call 404 behavior. These are significant behavioral traits that annotations do not convey, so the description adds substantial value.

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 front-loads the core action and result in the first sentence, then uses a bullet list for availability contexts and a final paragraph for prerequisites and security notes. Every sentence contributes useful information with no redundancy or 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 output schema exists to document return values, the description covers everything else an agent needs: when to call (after job completion), what to expect (URL and password), time-limited URLs, password security, and the self-hosted vs cloud contexts. No critical information is missing.

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

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

The single parameter 'id' is already described in the input schema as 'Migration ID' with 100% coverage. The description does not add any further semantic detail beyond repeating that it is for a migration, which is already present. Baseline 3 is appropriate since the schema carries the burden.

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 ('Fetch'), a precise resource ('downloadable migration package for a migration'), and the exact result (presigned URL to an AES-256-encrypted zip plus the password). It clearly differentiates from siblings like get_migration or get_migration_jobs by focusing on the package artifact and its delivery mechanism.

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

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

It explicitly instructs to check get_migration_jobs first to confirm the GENERATE_PACKAGE job is COMPLETED, and warns that calling too early returns 404. It also provides distinct use-case context for SUPABASE_SELF_HOSTED vs SUPABASE_CLOUD, giving the agent clear guidance on when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it explains that pendingAction must be followed exactly, describes the structure and purpose of nextActions, and notes that blocked entries are intentionally listed. It also assures the agent that the response contains no secrets, providing extra safety information beyond the annotations.

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

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

The description is long but every sentence carries weight. It front-loads the critical instruction ('START HERE') and purpose, then uses clear bullet points to explain pendingAction branches and nextActions semantics. The structure is highly organized, with no filler, making it easy for an agent to parse and act on.

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

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

Given that the tool has an output schema that documents return values, the description covers all necessary contextual aspects: when to call, how to interpret the response, how to handle pendingAction, and how to use nextActions. It even addresses edge cases like blocked entries and warns against premature actions, making it complete for its role as a conversational starting point.

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 there is nothing for the description to explain about parameters. The baseline for 0 parameters is 4, and the description correctly focuses on output behavior rather than parameter usage, which is appropriate here.

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: it is the first call in any Staticbot conversation, providing identity, integrations, plan limits, and outstanding actions in one request. It explicitly differentiates itself from siblings by being the starting point and the cheapest option, making it unmistakable which tool to use first.

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 ('START HERE', 'The first call of any Staticbot conversation') and detailed instructions on how to react to each pendingAction value, including when to stop and ask the user versus when to proceed. It also warns against inferring choices and gives clear direction on following nextActions, making the usage context fully explicit.

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 annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is safe to call without side effects. The description adds context about the preview stack limitation and the specific fields returned, but does not go into detail about permissions or rate limits. Since annotations cover the core behavioral traits, this is strong.

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, with the main purpose in the first sentence. It lists key return fields and ends with a relevant exclusion. No superfluous sentences; every word adds value.

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

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

The tool has a single parameter, full schema coverage, and an output schema (as indicated by the context signal), so the description does not need to explain return values. It covers the essential scenario and the preview stack limitation, making it complete for a read-only informational tool. Minor gap: no mention of when the webhook might not be configured or error cases, but that is acceptable.

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 100% coverage with a clear description for the 'id' parameter stating 'Deployment ID'. The description does not add additional parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate. No extra domain context is provided 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 clearly states the primary purpose: checking whether automatic updates are available and inspecting GitHub webhook state. It explicitly lists the returned fields, which helps distinguish it from related tools like get_auto_deploy_settings and update_auto_deploy_settings. The scope (deployment, not settings) is unambiguous.

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

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

The description provides clear context for when to use this tool (to check availability and webhook state) without explicitly naming alternatives or exclusion conditions. It notes that automatic updates do not apply to preview stacks, which is a usage boundary. However, it could be more explicit about when to use this versus get_auto_deploy_settings, but the sibling names and field list provide reasonable differentiation.

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

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

Annotations already establish read-only and non-destructive behavior. The description adds useful semantic context about what each flag controls, which is valuable, but it does not disclose additional operational behavior such as error cases or availability. This is acceptable given the annotations, but not exceptional.

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

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

Two sentences, front-loaded with the operation and resource, followed by compact definitions of the two flags. Every sentence earns its place with no filler or redundancy.

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

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

For a simple one-parameter read with an output schema, read-only annotations, and full schema coverage, the description is nearly complete. It loses one point because the sibling get_auto_deploy_info could be confused with this tool and no disambiguation is provided.

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

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

The only parameter, id, is fully described in the schema with 100% coverage, so the description does not need to restate it. The description adds no parameter-level detail, so the baseline of 3 is appropriate.

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

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

States a specific action and resource: 'Get the automatic-update flags for a deployment' and names the two flags. It is clear, but it does not explicitly distinguish itself from the similarly named sibling get_auto_deploy_info, so it misses the top bar for sibling differentiation.

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

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

No guidance on when to use this tool versus get_auto_deploy_info, or how it relates to update_auto_deploy_settings. The purpose implies a read use case, but there are no explicit when-to-use 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?

Annotations only state readOnlyHint=true and destructiveHint=false. The description adds crucial behavior: availability is limited to Supabase Cloud and pre-execution, the state is live (not a snapshot), and the exact workflow for presenting rows and project ref and passing to clean_migration_target. No contradiction with annotations.

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

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

The description is long but every sentence carries essential operational information: call timing, live/snapshot distinction, return field meanings, and the authorization hand-off. It is dense but not wasteful; the complexity of the tool justifies the length.

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

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

Even with an output schema present, the description adds the meaning of `available`, the per-scope rows, the required approval workflow, and the safeguard around clean_migration_target. For a tool with this much behavioral nuance, all context an agent needs to invoke it correctly is covered.

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

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

The single parameter 'id' is already fully described in the schema ('Migration ID') with 100% coverage. The description does not add further parameter-specific semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('inspect') and resource ('destructive target cleanup') and explicitly distinguishes this tool from get_migration's snapshot and clean_migration_target. An agent can immediately understand what this tool does and why it exists.

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

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

It gives explicit when-to-use ('Always call this immediately before presenting cleanup'), warns against relying on the earlier get_migration targetConflictReport, and tells the agent to not call clean_migration_target when available is false. This names the alternative tool and the condition that selects it.

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

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

Annotations already mark this as read-only and non-destructive, so the description does not need to repeat safety behavior. It adds value by telling the caller what data to expect (sync mode, webhook status, linked migration, deployment). No side effects or error conditions are described, but none are necessary for a read-only getter with this annotation coverage.

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

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

A single, front-loaded sentence contains all essential information with no filler. Every phrase 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 one-parameter, read-only retrieval tool with an output schema and annotations covering safety, this description is sufficient for an agent to select and call it correctly. The missing explicit sibling routing is a minor usage-guidance gap, not a completeness gap.

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

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

The single parameter 'id' is fully documented in the schema with type, format, and description ('Connected project ID'). The description adds no additional parameter-level meaning, which is acceptable given 100% 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?

The description uses a specific verb ('Get details') and resource ('connected project') and enumerates the key returned aspects (sync mode, webhook status, linked migration, deployment). This makes it clearly distinguishable from list_connected_projects (listing) and from get_deployment/get_migration (which target specific entities rather than a project aggregate).

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 is the tool to call when you need a single connected project's details, which is clear in context. However, it never explicitly says when not to use it or points to list_connected_projects or other siblings for alternative use cases. The guidance is left to inference from the name rather than stated.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description does not contradict them. The description adds significant behavioral context: it explains that 'dns' is present regardless of status, that 'requiredAction' is legacy and only set when WAITING, and that 'mailRecordsDetected' is a hard block on NS-change advice. It also covers failureSummary and terminal status handling.

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

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

Though lengthy, the description is well-structured with clear sections (statuses, response fields, per-domain actions, other fields, failureSummary). Every sentence serves a purpose, and critical guidance is front-loaded. It is comprehensive 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 (multiple DNS action states, legacy fields, external tool integration, hard blocks), the description is exceptionally complete. It covers all necessary interpretation rules, fallback behaviors, and edge cases, leaving nothing essential 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?

The input schema already fully documents the single 'id' parameter (uuid, 'Deployment ID') with 100% schema description coverage. The description does not add extra parameter semantics, but none are needed. This is a baseline 3 as the schema handles it.

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: to get the status of a deployment and per-domain DNS state, and explicitly says to poll for progress. It also lists the status flow (CREATED → PENDING → ... → COMPLETED/FAILED), which distinguishes it from listing tools like list_deployments and other deployment-related siblings.

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

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

It provides explicit when-to-use guidance ('Poll this for progress') and detailed instructions on how to interpret each DNS action (e.g., NO_ACTION, MANUAL_RECORDS_AT_REGISTRAR, OFFER_CLOUDFLARE_PUSH) and what to do or avoid (e.g., 'Do NOT suggest changing nameservers', 'obtain authorization before the external DNS write'). It also advises preferring 'dns' over legacy 'requiredAction'.

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

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

Annotations already identify it as read-only and non-destructive, and the description adds substantial behavioral context: the self-navigating pendingAction contract, previewDeployment progressing in the background after COMPLETED, skipGuard guardrails, and the boundary that MCP provides no human support or purchase routes. No statement contradicts the annotations.

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

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

The description is long, but the tool's state machine and edge cases justify the length. It opens with a crisp definition, uses bolded section labels for scanning, and each paragraph addresses a distinct operational concern without significant 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 a one-parameter read tool with an output schema and read-only annotations, the description covers all operational knowledge an agent needs: pendingAction interpretation, preFlightGate and targetConflictReport presentation, failureBanner handling, support-channel semantics, and previewDeployment polling rules with a concrete cadence. Nothing essential is missing.

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

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

The only parameter, id, is already fully documented in the schema as 'Migration ID' with 100% coverage. The description does not add parameter-specific semantics, which is acceptable for a simple UUID, so it earns the baseline rather than bonus credit.

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

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

The opening sentence states a specific verb and resource: 'Get the current status and phase breakdown of a migration.' It enumerates phases, key fields, and points to download_package as the follow-up for the zip, which also helps distinguish it from sibling action 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 gives explicit branch logic for almost every pendingAction type, including exclusions such as 'never skip cleanup', 'never resume a migration they paused without asking', and 'do not ask for the secret values'. It also specifies polling cadence and stop conditions, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context that this is scoped to AWS deployments for migration infrastructure, which is useful. However, it doesn't disclose return format, pagination, or what happens if the migration has no AWS deployments. With annotations covering safety, a 3 is appropriate.

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

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

Two sentences with no waste. The first sentence states the action and scope, the second provides context about when such deployments exist. Front-loaded 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?

The tool has a simple schema (one required id), an output schema exists, and annotations cover the safety profile. The description explains the AWS self-hosted Supabase context, which is the main contextual nuance. It doesn't describe the output structure, but the output schema exists so that's not required. Minor gap: no mention of what happens when no deployments exist, but that's not critical for a list operation.

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

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

Schema description coverage is 100% and the single parameter 'id' is described as 'Migration ID' in the schema. The description doesn't add parameter-level detail beyond the schema, but with full coverage the baseline of 3 is correct. The description does clarify the relationship between migration and deployments, which helps understand the id parameter's role.

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 all AWS deployments associated with a migration's infrastructure stack, and explains the context (migrations that deploy to AWS self-hosted Supabase create deployments for infrastructure provisioning). This distinguishes it from sibling tools like get_deployment or list_deployments by scoping to migration infrastructure deployments.

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 when to use this tool: when you need deployments for a migration's infrastructure stack, specifically for AWS self-hosted Supabase migrations. It doesn't explicitly name alternatives or exclusions, but the context about AWS self-hosted Supabase provides clear usage context. Sibling tools like get_deployment are for individual deployments, so the distinction is inferable.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is clearly safe to call. The description adds substantial behavioral detail beyond that: progressMessage semantics, skipGuard meaning, and the warning to read skipGuard before offering a skip to avoid a 400 error. This is exactly the kind of behavioral context an agent needs.

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

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

The description is long but dense and front-loaded with the primary action and definition. Every sentence contributes: usage purposes, progress reporting behavior, skipGuard semantics, and a caution about triggering a 400. No filler or repetition.

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

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

For a single-parameter read-only list operation with an output schema present, the description is complete. It covers what the tool returns conceptually, how to interpret progress fields, and how to avoid a common error when using the results with sibling skip tools. Nothing essential is missing.

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

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

The input schema fully documents the single parameter `id` as a UUID 'Migration ID' (100% schema description coverage). The description does not add parameter-level detail, but the schema already carries the burden, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get all jobs for a migration.' It then defines what a job is within the migration context and distinguishes this tool from higher-level migration and deployment tools by emphasizing the granular view and jobId retrieval for retry/skip.

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 says when to use the tool: to understand granular activity, diagnose failures, or find a jobId for retry/skip. It also gives concrete guidance on reporting progress and reading skipGuard. It does not explicitly mention alternatives like get_migration_deployments, so it lacks a true 'when-not-to-use' clause.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds valuable behavioral context: it explains that every override key is listed, with values returned for location-shaped keys and '[REDACTED]' for credential-shaped ones. This is beyond what annotations provide and helps set expectations about sensitive data handling. No contradiction.

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

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

The description is two sentences, front-loaded with the primary action ('Get details of a stack including its templates and config overrides') and then adding essential detail about redaction behavior. There is zero fluff, and every word earns its place. It is concise and well-structured.

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 has an output schema (though not displayed here) and the annotations already cover safety, the description covers the main return value categories (templates and config overrides) and the redaction behavior. It does not explain pagination or any fields beyond overrides, but for a get-by-id tool, this is reasonably complete. Minor gap: it doesn't state what happens if the stack doesn't exist, but that is typical and not required.

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 only one parameter 'id' with 100% coverage (it describes it as 'Stack ID'), so the schema already documents the parameter. The description does not add syntax or format details for the id, but with full schema coverage, the baseline is 3. However, the description implicitly indicates the id identifies the stack to fetch, and the parameter is simple. Slight credit for implying the id's role in fetching, but the schema already covers it, so a 3 or 4 is fair. I give 4 because the description's mention of 'stack' clarifies the resource type that the id refers to, adding slight semantic 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 'Get details of a stack including its templates and config overrides', specifying the resource (stack) and the type of information returned. It distinguishes itself from list_stacks (which likely lists stacks) and other get_* tools by focusing on stack details, though it doesn't name a specific sibling. The verb 'Get' is specific and the resource is clear.

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 when to use it: when you need details of a single stack. It does not explicitly state when not to use it or name alternatives, but among siblings like list_stacks and get_deployment, the context is reasonably clear that this tool is for a specific stack's details. There is no explicit exclusion or alternative guidance, so it's adequate but not explicit.

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

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

Annotations already mark this as read-only and non-destructive. The description adds useful behavioral semantics beyond that: healthy/transitioning/unavailable states, the polling loop, and the explicit warning not to treat a transitioning state as permission to create another project.

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 tightly packed sentences: what it reads, when to poll, and how to interpret the states. No filler or repetition; each sentence contributes to correct invocation and decision-making.

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 status-polling tool with a read-only annotation, a fully documented two-parameter schema, and an output schema, the description covers the essential workflow and stop conditions. The return fields are left to the output schema, as appropriate.

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

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

Schema description coverage is 100%, with both required parameters already documented, including projectRef provenance as create_supabase_project.id. The description does not need to repeat parameter details, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Read the lifecycle state of a Supabase project.' It grounds the tool in the Staticbot lifecycle, distinguishing it from bare listing tools like list_supabase_projects and from deployment/account status siblings.

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

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

Explicitly states when to use the tool: poll after create_supabase_project until healthy=true before using the project as a migration target. It also gives exclusion guidance: transitioning states mean wait, and unavailable=true means stop and report rather than creating another 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description supplements this with a status lifecycle (PENDING → IN_PROGRESS → COMPLETED/FAILED) and the PAUSED_FOR_REVIEW condition for destructive migrations. It also instructs the agent not to infer version fields, adding value beyond the structured annotations.

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

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

Three sentences, each carrying distinct value: what the tool returns, how to use its output correctly, and the status flow. No filler or repetition; the most important information is front-loaded.

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

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

For a read-only detail-fetching tool with an output schema, the description covers the essential semantics: the data available, the status lifecycle, and the PAUSED_FOR_REVIEW edge case. It could add a hint about parameter relationships, but the output schema and annotations cover the rest. Very close to complete.

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

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

Schema description coverage is 100%, so both parameters are already well-documented. The description adds no additional meaning about the parameters themselves (e.g., where to find runId or projectId), so it stays at the baseline for high 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?

The description clearly states it retrieves details of a specific sync run, enumerating the specific data included (status, versions, changes, errors). This distinguishes it from sibling tools like list_sync_runs (list) and get_sync_run_jobs (jobs) without ambiguity.

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

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

It provides clear context for when to use the tool (when needing details of a specific run) and includes a specific directive about using returned version fields when reviewing diffs. However, it does not explicitly mention alternatives or when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the diagnostic use case and clarifies that jobs are individual work units, which is useful context. It does not describe pagination, ordering, or the output shape, but the output schema exists and the read-only safety profile is covered by annotations.

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

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

Two sentences with no wasted words. The core action and resource are front-loaded, and the examples and diagnostic purpose are packed into the second sentence efficiently.

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

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

For a read-only list tool with a full output schema and 100% parameter coverage, the description is nearly complete. The only minor gap is that it doesn't mention whether jobs are returned in any particular order or whether the list could be large, but the output schema and annotations cover most of what an agent needs.

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

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

Schema description coverage is 100%, so both parameters (runId and projectId) are already documented in the schema. The description does not add parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Get'), a specific resource ('all jobs for a sync run'), and clarifies what jobs are with concrete examples ('apply_migration, deploy_edge_function, frontend_deploy'). It also distinguishes itself from the sibling get_sync_run by focusing on the job-level breakdown, so an agent can tell them 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 explicitly says to use this tool to diagnose sync failures at the job level, which gives clear context for when it is appropriate. It does not explicitly name alternatives or state when not to use it, but the job-level diagnostic purpose is enough to guide selection among siblings like get_sync_run and retry_sync_run.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral context: these are gaps that won't be re-offered by future syncs, each entry means the file exists but is missing from the DB, and it explicitly warns against automatic re-application. This goes beyond the annotations and gives the agent crucial safety guidance.

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 front-loaded: it starts with the core action, then explains the conditions, meaning, healthy case, and usage instruction. Every sentence adds value without redundancy. The length is justified given the complexity of the scenario.

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

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

With an output schema present, return value details are not needed. The description covers what the tool lists, why these gaps exist, what each entry signifies, the healthy case, and how to handle the results. For a list tool with one parameter, this is complete.

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

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

Schema description coverage is 100% for the single projectId parameter, which is already fully documented in the schema. The description does not add any new meaning about the parameter's format or constraints, but it doesn't need to since the schema covers it. 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 clearly states the tool's purpose: it lists SQL migrations that continuous sync failed to apply or skipped, and explains why they won't be re-offered. It distinguishes itself from sibling tools like list_sync_runs or get_sync_run by focusing on migration gaps rather than run history. The verb 'list' and specific resource (SQL migrations) make it unambiguous.

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

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

It provides explicit guidance on what to do with the output: report to the user and do NOT re-apply automatically. It also explains the healthy case (empty list) and implies when to use it (to identify schema gaps). While it doesn't name alternatives, the instruction not to re-apply is a clear usage directive that prevents misuse.

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

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

Goes well beyond annotations by disclosing that Staticbot never returns credential values, instructing to rely on `configured` to distinguish withheld from not set, and explaining that `migrationBackendDerived=true` means user input cannot take precedence. It also defines security-related statuses and how to handle them. This is substantive behavioral disclosure beyond readOnlyHint/destructiveHint.

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

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

The description is dense but every clause carries operational guidance — credential handling, migration field interpretation, and configOverride constraints. It is front-loaded with the core purpose and then details behavior; no filler, though the density makes it slightly heavy.

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

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

With an output schema present, the description covers all non-schema behavior: credential redaction, how to interpret `configured`, migration field semantics, configOverride restrictions, and security-review actions. An agent has enough context to call the tool and correctly interpret the result.

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

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

The only parameter, `id`, is already fully described in the schema as 'Template ID' (100% coverage). The description adds no additional meaning or format details beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description opens with 'Get details of a template including its backend-classified configuration variables' — a specific verb and resource that distinguishes it from the sibling list_templates. The singular 'template' and 'details' clearly indicate this is a single-item retrieval, not a list operation.

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

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

The description gives rich conditional guidance for handling migration fields and configOverride, but it does not explicitly state when to use this tool versus alternatives like list_templates. Usage context is implied by the purpose rather than explicitly contrasted with siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds significant behavioral context beyond that: it instructs to 'render the response; do not derive or repair it', explains how to handle null managed values, requires surfacing every notice verbatim, and explicitly warns never to invent an account id or send infrastructureOwnership. This is rich, non-obvious behavior that an agent would not infer from the schema or annotations alone.

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

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

The description is longer than average but well-structured: it opens with the core usage scenario, then uses a bullet list to explain response fields, and finally provides decision logic and integration guidance. Every sentence adds value—there is no fluff. It could be slightly more concise by merging the parameter explanation with the schema, but it is efficient given the complexity.

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

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

Given that an output schema exists (though not shown), the description adequately explains the key output fields (managed, customerOptions, notices, selectedValue) and how to handle them. It also covers the decision logic and the exact value to pass to create_deployment. It does not mention pagination or error handling, but for a tool that returns a list of options, this is not a critical omission. It is complete enough for 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 100%: the stackId parameter is already documented in the schema as 'Optional stack ID. Supply it before create_deployment so managed, notices, and selectedValue reflect that stack's AWS hosting rules.' The description repeats this same reasoning without adding new semantic details (e.g., format, constraints, or examples). Since the schema already covers the parameter fully, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: to choose which AWS account will own a deployment for a stack with deploymentTarget AWS_STATIC. It specifies the exact condition and the action to take, and it distinguishes itself from the sibling list_cloudflare_hosting_targets by referencing AWS specifically. It also ties to create_deployment, making its role in the workflow unambiguous.

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

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

The description provides explicit when-to-use guidance ('when an existing stack's deploymentTarget is AWS_STATIC'), and it explains the sequencing ('before create_deployment'). It also gives detailed decision rules: use it automatically if one option, let user decide if several, and do not create a deployment if none. It even instructs how to pass the returned value to create_deployment, leaving no ambiguity.

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

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

Annotations only provide readOnlyHint and destructiveHint, which are minimal. The description adds substantial behavioral context: token scoping, why the integration alone doesn't identify the app, security warnings about personal access tokens, error handling semantics, and the note that it contains no secrets. This goes well beyond the annotations and is critical for correct and safe usage.

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. It starts with the primary purpose, then proceeds through usage, error handling, and security in a logical order. Each paragraph addresses a distinct concern (purpose, selection guidance, error interpretation, token safety), and the structure aids clarity despite the length.

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

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

The description covers all essential aspects: what the tool lists, why it's needed, how to use its output, how to handle errors, and critical security practices. With an output schema present, it needn't detail return values, and it does not leave any obvious gaps for correct invocation.

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

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

The single parameter `base44IntegrationInstanceId` is fully documented in the schema with a clear description and source reference. The description adds contextual rationale for the parameter's importance (token scoping) but does not add new meaning about the parameter itself. Since schema coverage is 100%, a baseline of 3 is appropriate.

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

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

The description begins with a clear verb and resource: 'List the Base44 apps a connected Base44 integration can migrate' and immediately ties it to the migration workflow by referencing create_migration. It distinguishes this tool from siblings by clarifying its role as a prerequisite enumeration 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?

Explicitly states when to use it ('Call this before create_migration for any BASE44_NATIVE migration'), provides a direct instruction for the output ('Pass the chosen app's `id` as create_migration's `base44AppId`'), and includes behavioral guidance on not guessing apps. It also details error cases (empty list, 400) with actionable remedies.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the description adds substantial behavioral context: managed is always present and valid, customerOptions values must be passed back verbatim, notices explain missing accounts, and the agent must not decide for the user. This goes well beyond the annotations.

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

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

The description is longer than average but well-structured: purpose and usage come first, response semantics are bulleted, and the decision rule and preflight dependency are clearly separated. It earns its length, though the repeated emphasis on not deciding for the user could be slightly tightened.

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

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

Given the single optional parameter, existing output schema, and complex decision context, this description is complete. It covers when to call, what the response fields mean, how to handle them, what not to do, and which follow-up tool to call before creating resources.

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

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

Schema description coverage is 100%, and the single optional stackId is already well-documented in the schema. The description adds the behavioral consequence of supplying stackId—selectedValue and selectedHostname come back as defaults—but does not add new syntax or format details, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the Cloudflare accounts this app can be hosted in', and immediately distinguishes the managed Staticbot option from user-connected Cloudflare accounts. It clearly differentiates from sibling list_aws_hosting_targets by naming the Cloudflare 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 explicitly says when to call it: 'Call this before create_stack or create_deployment for a Cloudflare Workers / SSR app whenever the user has a connected Cloudflare account'. It also names the follow-up dependency, preflight_cloudflare_hosting, and gives a decision rule based on customerOptionsAvailable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral guidance beyond annotations by warning that hasPreview alone is insufficient and that deploymentStatus must be used to distinguish build states. This helps the agent interpret results correctly.

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

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

Two sentences deliver the core purpose, the return fields, and a critical interpretation caveat. Every sentence earns its place, and the most important usage warning is placed at the end for emphasis without bloating the definition.

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 one-parameter read-only list operation with an output schema and read-only annotations, the description is complete. It covers what is returned, how to interpret statuses, and the correct scope of the operation. No additional context is needed for correct invocation.

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

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

Schema description coverage is 100%, with the only parameter 'id' documented as 'Connected project ID'. The description reinforces that the tool operates on a connected project but adds no new parameter-level meaning. Baseline 3 is appropriate since the schema carries the full burden.

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

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

The description names a specific verb ('List'), a specific resource ('tracked branch previews for a connected project'), and enumerates the key fields returned (preview deployment ID, raw deployment status, preview URL, dashboard status URL). This clearly differentiates it from sibling tools like list_connected_projects and get_connected_project.

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

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

The description clearly conveys when to use this tool: to list every tracked branch preview for a connected project. It also provides usage guidance on interpreting deploymentStatus versus hasPreview. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over nearby list/get tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds domain context about connected projects but does not disclose behavior such as pagination, return format, or filtering nuances beyond the schema-provided syncMode 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 two sentences. The first is direct and front-loaded. The second adds context about connected projects and a hint about enabling continuous sync, which is somewhat tangential but not verbose.

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

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

With an output schema present, return values are covered. The description explains the domain and gives context, but does not mention pagination or error handling, which are minor for a simple list operation. Overall adequate for the tool's simplicity.

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

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

Schema coverage is 100% for the single parameter (syncMode), and the description does not add any additional meaning or usage details beyond what the schema already provides. Baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('all connected projects'), which clearly distinguishes it from get_connected_project (single project). The scope is explicit and unambiguous.

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

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

The description explains what connected projects are but does not explicitly mention when to use this tool versus alternatives like get_connected_project or when not to use it. The 'all' qualifier implies it's for listing the entire set, but no explicit guidance is given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the semantic that a deployment represents an execution of infrastructure, which provides useful domain context but does not disclose additional behavioral traits like auth requirements, rate limits, or pagination. Given the annotations, the description adds some value but not rich behavioral disclosure.

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

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

Two sentences with zero waste. The main action ('List all deployments') is front-loaded, the optional filter is mentioned, and the domain definition is added in a second sentence. No redundant phrasing.

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 simple (list with optional filter), has an output schema to cover return values, and annotations cover safety. The description provides the purpose, the optional filter, and the meaning of a deployment, making it complete for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100% and the parameter 'stackId' is already described as 'Filter deployments by stack ID'. The description repeats this with 'Optionally filter by stackId' without adding new meaning or format details. Baseline of 3 is appropriate when the schema carries the parameter documentation.

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

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

The description states a specific verb ('List') and resource ('deployments'), and distinguishes itself from siblings like get_deployment, create_deployment, and start_deployment by clearly indicating it lists all deployments. It also adds domain context ('Each deployment represents one execution of a stack's infrastructure') that clarifies what is being listed.

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 indicates that this tool lists all deployments with an optional filter by stackId, which provides clear context for when to use it. However, it does not explicitly mention when not to use it or name alternatives (e.g., 'use get_deployment for a single deployment'), so it lacks explicit exclusions but is otherwise clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds the deprecation status, the return format (flat array with htmlUrl), and a specific instruction about not claiming public-repository requirements. These go beyond the annotations and are useful for correct invocation.

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

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

The description is front-loaded with the deprecation warning and alternative, then covers usage, return format, and a caution in a structured manner. It is slightly long but every sentence serves a purpose, with 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?

For a deprecated tool, the description is remarkably complete: it tells the agent what to use instead, how to obtain the required parameter, what the return shape is, and a behavioral caution. Combined with the output schema and annotations, nothing essential is missing.

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

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

Schema coverage is 100% and the parameter description already states it comes from list_integration_instances. The description reinforces this by instructing the agent to call list_integration_instances first and pass the selected instance ID, adding practical 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 lists public and private GitHub repositories accessible through a connected Staticbot GitHub integration, and explicitly names the alternative tool (list_source_repositories) that supersedes it. This distinguishes it from siblings and leaves no ambiguity about its function.

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

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

It explicitly says 'Deprecated — use list_source_repositories' and provides a step-by-step usage path: call list_integration_instances first, then pass the selected GitHub instance ID. It also includes a behavioral caution about not claiming Staticbot requires a public repository, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint=true, destructiveHint=false) already cover the safety profile. The description adds context about the 'type' field on results, but that's more output semantics than behavioral disclosure. There's no mention of limits, pagination, or any side effects beyond the read-only nature, which is already covered by annotations. Given the annotations, a 3 is appropriate.

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 about 70 words across four sentences, all relevant. It front-loads the core purpose and then builds on it with mapping and exclusions. Slightly verbose in the tail (repeating the core purpose), but efficient and structured. A 4 is fair.

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

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

For a zero-parameter list tool with an output schema present, the description is thorough: it states scope, provides mapping for the output, and names the sibling that covers repository resolution. It doesn't mention pagination, but that's likely minor for this tool. Overall, an agent has everything needed to call and interpret it correctly.

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

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

There are zero parameters, so the schema provides no meaning. The description compensates fully by explaining how to interpret the result: each instance has a 'type' field and maps to specific IDs (supabaseIntegrationInstanceId, githubIntegrationInstanceId, sourceIntegrationInstanceId) for create_migration. This is far beyond the baseline of 4 for 0 params, adding direct usage guidance for the output.

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

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

The description opens with a clear verb+resource: 'List all connected integrations for the organization.' It also differentiates itself from sibling list_source_repositories by explicitly stating what this tool is for (instance IDs, checking if any source-control account is connected) and that repository resolution belongs elsewhere.

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

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

The description provides explicit when-to-use guidance: 'Use this tool for the supabase/base44 instance IDs' and 'to check whether any source-control account is connected at all.' It also clearly routes repository resolution to an alternative: 'To resolve a repository, call list_source_repositories instead.' This is a textbook example of usage guidelines.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description doesn't need to restate that. It adds useful context about what migrations orchestrate, but it does not disclose behaviors such as pagination, ordering, or response size; still, the bar is lower because annotations cover the main risk.

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

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

Two sentences with no filler. The primary action is front-loaded, and the domain context is provided in a compact second sentence that helps with tool selection without bloating the description.

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

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

For a read-only listing tool with one optional parameter and an output schema, the description is complete. It explains what a migration is, what the tool does, and that filtering is possible—nothing critical is missing 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 schema describes the single parameter fully with an enumerated list, so the description need not add much. Mentioning 'Optionally filter by status' matches the schema but doesn't add new meaning beyond what the structured definition already provides.

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

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

The description opens with a specific verb and resource ('List all migrations'), immediately distinguishing it from single-migration tools like get_migration. It also clarifies the domain meaning of a migration, which helps an agent understand the tool's scope before calling it.

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

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

The description gives clear context that this is the general listing tool, with an optional status filter. It doesn't explicitly name alternatives or exclusions, but the self-contained nature of a list operation makes the primary use case unambiguous.

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

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

Annotations already convey readOnly and non-destructive behavior. The description adds useful behavioral context beyond that: results are restricted to valid rollback targets, are commit-pinned, and are ordered newest first, plus the critical caveat that SHA/label values must not be used as rollback targets.

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 tightly packed sentences: the first states the core behavior and ordering, the second delivers the essential usage constraint. Every clause earns its place with no redundancy or 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 a one-parameter schema, comprehensive annotations, and an output schema, the description covers everything an agent needs to call the tool correctly and use its result correctly. It even preempts the most likely misuse.

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

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

Schema coverage is 100% for the single `id` parameter with a clear 'Deployment ID' description. The description reinforces that the list is 'for a deployment,' but adds no new parameter-level detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific verb ('List'), a specific resource ('commit-pinned website template versions that are valid rollback targets for a deployment'), and an ordering ('newest first'). It clearly differentiates this from generic template listing tools by centering on rollback targets and naming rollback_website.

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

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

The description gives explicit usage direction: use only a returned `templateId` with rollback_website, and explicitly warns against inferring a target from a commit SHA or version label. This tells the agent when and how to consume the result, and what not to do.

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

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

Beyond the readOnly and non-destructive annotations, the description discloses important behaviors: passing an instance ID hides other accounts, sources[] may include unavailableReason entries, empty sources require user action, and the tool should never be misrepresented as requiring a public repository. It also outlines the exact response shape and downstream consequences, which is far beyond the annotation baseline.

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, covering purpose, invocation, parameter behavior, response shape, matching logic, failure modes, and downstream actions. It is front-loaded with the core purpose, then flows logically through usage details, and contains no tautological or filler sentences.

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

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

Given the tool's workflow-critical role, the description is remarkably complete: it covers normal usage, ambiguity resolution, unavailable sources, empty sources, and the correct integrationInstanceId to pass downstream. The existing output schema and annotations reduce the need for more return-value detail, so nothing essential is missing for an agent to call this correctly.

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

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

The schema already provides a strong description for integrationInstanceId, and coverage is 100%, so the baseline is 3. The main description adds value by explaining why passing the parameter narrows the listing and warns 'only do that when the user has already chosen an account.' This contextualizes the parameter without duplicating the schema.

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

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

The description opens with a precise verb and resource: 'List all public and private repositories accessible through the organization's connected Staticbot source-control integrations — GitHub and GitLab.' It also clearly distinguishes itself from provider-specific or single-account tools by emphasizing that it covers every connected account in one call, making its scope and identity unambiguous.

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

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

The description provides strong usage guidance: 'Call this whenever a workflow needs a repository' and explains when to pass the optional integrationInstanceId ('only do that when the user has already chosen an account'). It does not explicitly name sibling alternatives such as list_github_repositories, but the 'whenever a workflow needs a repository' directive effectively routes the agent correctly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful domain context about stacks, but does not disclose behavioral traits such as whether the list is workspace-scoped, pagination behavior, or if only stacks in a certain state are returned. It adds some context but not rich behavioral detail beyond the annotations.

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

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

The description is three sentences with no filler. The primary action is front-loaded in the first sentence, and the following sentences provide relevant domain context that helps the agent understand the resource being listed. 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 zero-parameter list tool with an output schema and annotations covering safety, the description is nearly complete. It explains what a stack is and that it lists all stacks. It could be more explicit about scope (e.g., all stacks in the account vs. workspace), but the output schema likely covers the return shape, and the complexity is low.

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 there is nothing to explain. The baseline for zero parameters is 4, and the description does not need to add parameter information. The schema coverage is effectively 100% since no parameters exist.

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 and resource ('List all infrastructure stacks') and further defines what a stack is in this domain (groups templates with domain assignment, can have multiple deployments). This clearly distinguishes it from sibling tools like list_templates, list_deployments, and get_stack, which target different resources or filters.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description simply states the action and domain context, but does not mention that get_stack should be used for a specific stack or that list_deployments should be used for deployments. No exclusions or alternative routes are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds that the tool lists 'accessible' organizations and that the id should be used unchanged, which is useful workflow context, but it does not disclose any side effects or deeper behavioral details beyond that.

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

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

The description is three sentences long, front-loaded with the primary action, and efficiently conveys the workflow, selection guidance, and a caution. It is concise without being terse, though the instruction to 'present the organization names' could be seen as slightly redundant with 'list'.

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 and the clear workflow guidance, the description covers the essential context for invoking the tool correctly. It explains the relationship to create_supabase_project and the selection rule, though it does not detail the output format or any edge cases.

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

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

The input schema already fully documents the single parameter with a clear description and source reference. The tool description does not add any additional meaning about the parameter itself, so it stays at the baseline for high 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?

The description clearly identifies the tool as listing Supabase organizations accessible through a connected integration instance, which distinguishes it from siblings like list_supabase_projects. It also positions it in a workflow by mentioning create_supabase_project, making its purpose unambiguous.

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

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

The description explicitly instructs to call this before create_supabase_project and to present the organization names to the user, which provides clear when-to-use context. It also cautions against guessing when multiple organizations are available, but it does not explicitly mention alternative tools or when not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safe read-only nature. The description adds meaningful behavioral context by stating which projects are usable as migration targets (ACTIVE_HEALTHY only) and what fields are returned. This goes beyond the structured annotations without contradicting them.

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

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

The description is four sentences and every sentence carries useful information: purpose, return fields, downstream usage, and an alternative action. It is slightly front-loaded with the core list action, and the guidance about presenting choices is actionable but not bloated. A tight 4.

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 one-parameter read-only list tool with an output schema present and annotations covering safety, the description is complete. It explains the required instance ID context, the fields returned, the ACTIVE_HEALTHY restriction, and the follow-up options. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100% and the only parameter, supabaseIntegrationInstanceId, is already described in the schema as coming from list_integration_instances. The description does not add new parameter-level semantics beyond mentioning how the result id is used downstream, which is not directly about the parameter. Baseline 3 applies.

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

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

The description begins with a specific verb and resource: 'List all Supabase projects accessible through a connected Supabase integration instance.' It also enumerates the returned fields (name, reference ID, region, status), making the tool's output scope clear. This distinguishes it from sibling list tools like list_supabase_organizations and list_supabase_regions.

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

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

The description gives explicit guidance on using the output: use the project's id as targetSupabaseProjectRef when creating a migration, and only ACTIVE_HEALTHY projects are valid targets. It also instructs the agent to present the list and let the user choose, or offer create_supabase_project as an alternative, clearly routing to the sibling.

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 annotations already mark this as read-only and non-destructive. The description adds meaningful behavioral context: it is a pre-step for create_supabase_project, the returned region id should be passed through unchanged, and the tool should be used to surface choices rather than default. This goes beyond the annotation baseline without contradicting it.

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 sentences front-load the verb, resource, and context, then add the key usage rule. There is no filler or repetition of schema fields.

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

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

For a lightweight lookup tool with one fully documented parameter, explicit annotations, and an output schema, nothing essential is missing. The description also covers the important pre-call behavior and user-preference handling, making it complete in 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 coverage is 100%, so the single parameter is already fully documented as 'Supabase integration instance ID (from list_integration_instances)'. The description does not add new parameter-level meaning, but the schema carries the burden sufficiently; baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the regions Staticbot supports when creating a customer-owned Supabase project.' It clearly distinguishes this from siblings like create_supabase_project and list_supabase_projects by narrowing it to region listing and project creation context.

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

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

It gives explicit sequencing: 'Call this before create_supabase_project' and says to use the selected region id unchanged. It also provides behavioral guidance for the ambiguous case where the user has no location preference: explain options rather than silently choosing one.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about what a sync run is (applying migrations, deploying edge functions, rebuilding frontend), which helps the agent understand the domain. It doesn't disclose pagination, ordering, or filtering behavior, but for a list operation with annotations covering safety, this is adequate.

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

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

Two sentences, front-loaded with the core purpose ('List sync run history'), followed by a useful definition of what a sync run is. No wasted words.

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

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

The tool has an output schema, so return values are documented elsewhere. The description explains the domain concept (sync run) and the scope (history for a connected project). It doesn't mention pagination or ordering, but for a simple list-by-project tool with one parameter and an output schema, this is nearly 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 100% — the single parameter 'id' is described as 'Connected project ID' in the schema. The description doesn't add parameter-level detail beyond that, but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool lists sync run history for a connected project, and explains what a sync run represents. It distinguishes itself from related tools like get_sync_run (single run) and retry_sync_run (action on a run) by focusing on history listing.

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 is for viewing history of sync runs for a connected project, which is clear context. It doesn't explicitly state when not to use it or name alternatives, but the sibling context and the phrase 'history' make the use case clear enough.

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

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

Annotations already cover read-only and non-destructive safety, so the description adds value by disclosing the slim response fields, the fact that templates feed both hosting and migration, and the important sourceLabel nuance when repository names collide. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core purpose and response shape, and every subsequent sentence adds actionable guidance about get_template, reuse, creation, and user choice. It is dense but each clause earns its place.

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

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

For a zero-parameter list tool with an output schema and read-only annotations, the description is complete. It explains what is returned, how to get more detail, how the results should influence the next action, and how to handle ambiguous repository scenarios.

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 already covers everything, so there is no parameter documentation burden. The description appropriately avoids inventing parameter details and instead focuses on outputs and decision workflow.

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 precise verb and resource: 'List available templates', and immediately distinguishes itself from the related get_template tool by noting the slim response shape versus full details. It also places templates in the broader hosting and migration workflow, so an agent can tell exactly what this tool is for.

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

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

The description gives explicit routing guidance: use get_template for full details with config variables, and use list_source_repositories when needing to resolve a repository. It also prescribes the decision procedure for reuse versus creation and when to ask the user, which is strong usage direction.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, which do not describe the nuanced behavior. The description adds the key behavioral detail that the current job finishes while new jobs are not started, which is valuable beyond the annotations. However, it does not discuss reversibility or error conditions, but that is partially covered by the output schema.

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

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

Two concise sentences with no redundant information. The action is stated first, followed by the behavioral nuance and the alternative tool, all in a clear and front-loaded structure.

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), the presence of an output schema, and the annotations covering safety, the description covers the essential aspects: the action, the nuance about jobs, and the path to resume. It could mention preconditions (e.g., migration must be running), but that is implied by 'running migration'. Overall, it is complete enough for correct invocation.

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

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

Schema description coverage is 100% for the single parameter 'id', which is already described as 'Migration ID'. The description does not add any additional semantic detail about the parameter, so it aligns with the baseline of 3 for high 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?

States the specific action 'Pause a running migration' with a clear verb and resource. It also differentiates from siblings by noting that the current job finishes while new jobs are prevented, and explicitly names resume_migration as the counterpart. This unambiguously identifies the tool's purpose.

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 guidance by stating the effect on in-progress and future jobs, and explicitly directs the user to resume_migration to continue later. It lacks an explicit 'when not to use' clause, but the context is sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'it never creates, deletes or takes over anything.' It goes beyond annotations by explaining the staleness risk ('permissions and DNS can change'), the meaning of ok:true/false, and how to handle warnings. This is rich behavioral context that helps the agent act correctly on 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 structured with a clear purpose line, a 'How to use the result' section with bullet points, and a final constraints paragraph. Every sentence earns its place—no fluff. The most important info (purpose and read-only) is front-loaded, and the result-handling rules are logically organized.

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 (two params, conditional behavior, staleness), the description covers everything an agent needs: when to call, how to interpret results, constraints on hostname, and the need to re-call after changes. An output schema exists, so return-value details are not needed. The description is complete 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 coverage is 100% (both parameters have descriptions), but the description adds critical semantics: for a customer choice, hostname must be a domain in an account zone, autogenerated subdomains are forbidden, and apex domains are supported. It also instructs to pass the choice value through unchanged. These constraints are not in the schema and are essential 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 opens with a precise verb+resource: 'Check that a hosting choice and hostname can actually be deployed, before create_stack or create_deployment.' It clearly names the two sibling tools it precedes, distinguishing its role as a preflight gate. The read-only nature is stated explicitly, and it even clarifies it applies to the managed choice as well, leaving no ambiguity about 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 gives explicit when-to-use guidance ('before create_stack or create_deployment') and instructs to call it again after any user change because the answer can go stale. It also states to call it the same way for either hosting option. While it doesn't list exclusions, the context is unambiguous and the alternative tools are named, so an agent knows exactly when to invoke this.

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

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

Annotations indicate non-read-only and destructive, and the description adds meaningful context: it is an external DNS write, idempotent, never changes nameservers or mail records, and requires user authorization. This goes beyond the bare annotations, though it doesn't explicitly mention that existing DNS records may be overwritten (inferred by 'push' and destructiveHint). No contradiction with annotations.

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

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

The description is longer than a simple two-liner, but every sentence earns its place: purpose, effects, prerequisite call, parameter sourcing, authorization, exclusions, output handling, and fallback. It is well-structured and front-loaded with the core action, even if slightly dense.

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

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

For a high-risk external DNS write, the description covers the full invocation path: how to prepare, what to pass, what to avoid, what to present to the user, and how to handle the response. With an existing output schema and annotations already covering return structure and safety flags, this description is effectively 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 100%, with both parameters already described. The description adds value by explaining where the IDs come from (deployment response and DNS item) and explicitly warns 'Do not infer a domain ID,' which is not fully captured in the schema alone.

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

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

The description states a specific verb and resource: 'Push ... certificate-validation and website-routing DNS records into the customer's linked Cloudflare zone.' It further distinguishes itself by noting it never changes nameservers or mail records, which clearly separates it from other DNS-related sibling tools like recheck_dns_verification or preflight_cloudflare_hosting.

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 instructs to first call get_deployment, select the OFFER_CLOUDFLARE_PUSH item, and use the returned deployment id and domainId. It also gives clear when-not-to-use guidance: 'Do not infer a domain ID, use this for MANUAL_RECORDS_AT_REGISTRAR, or describe it as DNS delegation,' and names the fallback (manual records at the current provider).

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

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

The description discloses important behavioral details beyond annotations: null result indicates no applicable custom hostname, verificationErrors should be surfaced, and the domain should not be reported live unless both statuses are active. This adds context about return interpretation and error handling.

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

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

The description is concise but includes multiple clauses and conditions. It is not overly verbose, and all sentences contribute useful information. A slight trim could improve it, but it is well-structured.

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 description explains the expected return values, null handling, and success criteria, the description is complete for an agent to use the tool correctly. No critical missing information.

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 already has 100% coverage for the single parameter deploymentId, with a clear description. The tool description does not add extra parameter semantics beyond reiterating the deployment context, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to retry custom-hostname domain-control validation for a Cloudflare Workers deployment and return refreshed status. It uses specific verbs and resources, and distinguishes from related tools like push_dns_to_cloudflare by explicitly noting it does not write DNS records.

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

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

Provides explicit conditions for when to call: after DNS records are published or when the user explicitly asks to recheck verification. It also clarifies what the tool does not do (write DNS or change nameservers), guiding the agent away from incorrect use.

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

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

Annotations already declare destructiveHint=true, so the risk is communicated. The description adds useful behavior beyond annotations: it explains that the operation redeploys the currently pinned template by default, that useLatest changes this behavior, and that a worker job ID is returned for polling. No contradiction with annotations.

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

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

Three compact sentences, with the core action first. Every sentence adds value: the default behavior, the version toggle, and the follow-up polling step. Nothing is redundant.

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

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

Given the annotations, output schema, and full parameter schema coverage, the description is sufficient. It captures default behavior, the version option, and the post-call workflow. A minor gap is that it does not describe any side effects or prerequisites beyond the required id, but those are largely covered by the schema and destructive annotation.

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

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

Schema coverage is 100%, so the schema already documents id and useLatest fully. The description adds a little meaning by explaining the pinned-template default, which maps to useLatest, but it does not substantially clarify id beyond the schema's 'Deployment 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?

The description states a specific verb and resource: 'Rebuild and redeploy the static website component.' It also distinguishes the operation from get_deployment by mentioning its job-tracking workflow and from rollback_website by the 'redeploy' and 'template version' language.

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

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

It clearly explains when to set useLatest=true versus relying on the pinned default, and tells the agent to poll get_deployment for progress. It does not explicitly contrast with create_deployment or start_deployment, but the workflow guidance is strong enough for most use cases.

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

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

The description adds crucial behavioral context beyond annotations: it mandates user consent before invocation ('MUST present these options... and ask them to choose'), and explains the effect of each action (recheck for drift, abort to skip migration). This complements the destructiveHint=true annotation by detailing the destructive nature of the abort option.

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

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

The description is two sentences, front-loading the purpose and immediately stating the critical user-interaction requirement. It contains no unnecessary words and places the critical constraint in an 'IMPORTANT' note.

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 and a 100% schema description coverage, the description provides all necessary information: the function, the mandatory user interaction, and meaning of each action. An agent can correctly invoke this tool without needing additional external knowledge.

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 describes parameters but gives only a generic description for action ('Resolution action'). The description adds semantic meaning to the enum values, clarifying that 'recheck' means re-checking source schema for drift and 'abort' means skipping the migration. This goes beyond the schema's 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?

The description states a specific verb ('Resolve') and resource ('MANUAL_REVIEW_SCHEMA_GAP gate'), which clearly identifies the tool's function. It also lists the two resolution options, making the purpose unambiguous compared to sibling tools like skip_migration_job or confirm_migration.

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 instructs the agent to present the options to the user and obtain a choice before calling, providing a clear pre-condition. It does not, however, compare this tool to siblings or state when not to use it, though the gate-specific naming gives context.

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

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

Annotations already signal a mutating, non-destructive operation, so the description's added status constraints and prerequisite (manual step completed) are valuable behavioral context. It does not describe downstream effects in detail, but the annotation coverage lowers the burden and there is no contradiction.

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

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

The description is two short, front-loaded sentences: the first states what the tool does, and the second gives the usage condition. No filler or 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?

For a single-parameter mutation with an output schema, the description supplies essential state preconditions, usage timing, and a concrete example. It could explicitly mention behavior when called on a migration in an invalid state, but the description is adequate for correct invocation.

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

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

The input schema already documents the only parameter, id, as a required UUID migration ID with 100% coverage. The description adds no further parameter-level detail, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb-resource pair, 'Resume a migration', and further scopes it to exact states: PAUSED_BY_USER or PAUSED_FOR_USER_ACTION. This clearly differentiates it from siblings like pause_migration, retry_migration_job, and confirm_migration.

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