kad.dev

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

Rich disclosure beyond the annotations: server-side blocking, hard deadline behavior, timed_out=true with the plan still live, resumability by re-calling with the same plan_id, durability of state across dropped connections, and the key fact that a human approving in the dashboard is what actually executes the action. This is consistent with readOnlyHint=true — the tool observes, it does not decide.

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, then layered with deadline and durability semantics in a small number of dense sentences. The durable-state sentence partly repeats the resumption point, a minor redundancy, but nothing is padding.

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

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

With annotations covering the safety profile and an output schema covering return shape, the description supplies everything else an agent needs: when to call, how long it blocks, what a timeout looks like, how to resume, and who actually executes the action.

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 baseline is 3; the description still adds value by explaining that plan_id originates from a gated tool's pending_approval result and that reusing the same id resumes the same wait, plus that timeout_s bounds every call. The 45/55 numbers duplicate the schema, keeping it from a 5.

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

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

States a specific verb and resource ('Waits for a parked plan to be decided') and pins down the exact lifecycle it observes: blocks until the plan reaches a terminal status (applied, rejected, expired, failed) and returns it. This is clearly distinguishable from the polling sibling get_plan_status because blocking vs. returning a snapshot is spelled out.

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

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

It tells the agent precisely when to use it: the plan_id comes from a tool result with status pending_approval, and a timed-out call should be resumed with the same plan_id. There is no explicit exclusion naming get_plan_status as the non-blocking alternative, so the when-not is left implicit.

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

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

Goes well beyond the annotations by disclosing the first-build side effect, the 72h temporary-project fallback when no permanent slot exists, the expires_at/notice reply shape, the partial-failure behavior (project_id returned even if the build fails to start), and the read-write token requirement. The auth prerequisite and non-idempotent creation semantics are exactly the kind of context annotations can't carry.

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

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

Purpose and primary return values are front-loaded, and each subsequent clause adds distinct behavioral information. It is dense and somewhat long, but nearly every sentence earns its place; minor tightening possible around the temporary-project explanation.

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

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

For a 12-parameter mutation with an output schema, this covers the remaining gaps an agent would care about: side effects, fallback behavior, partial-failure recovery, auth requirements, and the explicit out-of-scope operation. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so all 12 parameters are already documented. The description adds only marginal meaning beyond that — it restates that ref defaults to the default branch and that framework is auto-detected, both already present in 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?

States a specific verb+resource ("Create a new kad.dev project from a git repository URL") plus the side effect of triggering the first build. This is clearly distinguishable from siblings like deploy_project (redeploy), list_projects (read), and delete_project (removal, explicitly noted as unavailable over MCP).

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

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

Gives concrete routing guidance for the failure case ("retry with deploy_project") and clarifies that whole-project deletion must go through the dashboard/API. It does not give general when-to-use guidance versus list_projects or deploy_files, but for a creation tool the context is largely self-evident.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: what resources are destroyed, that the deployment disappears from list_deployments, that the commit stays in the timeline, delayed space reclamation via promote/registry cleanup, rebuild-on-next-deploy behavior, and the read-write token requirement.

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 critical 'destructive and irreversible' warning is front-loaded and nearly every sentence carries behavioral information. However, it is one dense unbroken paragraph with a couple of hard-to-parse clauses (the keep_image/stop-release sentence mixes kept and removed resources), which slows scanning of a destructive tool.

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

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

For a destructive 3-parameter tool with an output schema already present, this covers everything an agent needs: prerequisites, refusals, side effects, deferred storage reclamation, and recovery paths. No material gap remains.

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 would be 3, but the description adds genuine meaning the schema lacks — notably the counterintuitive consequence that keep_data=true removes only the build image, and that either single-resource choice preserves the commit in the timeline. It does not state defaults as clearly as the schema, but it is still additive.

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

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

Opens with a specific verb and resource plus a safety qualifier ('Destructive and irreversible. Deletes a commit's data, build image, or both (by job_id)'). The scope is precise enough to separate it from siblings like stop_commit, demote_commit, and rollback_commit without consulting their schemas.

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 choose each mode: keep_image for keeping the commit deployable, keep_data for removing only the build image, and the prerequisite 'stop the release first, including sleeping releases'. It also names the hard exclusions ('Refuses the canonical commit and both keep options together'), which is exactly the when-not guidance an agent needs.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial context beyond them: irreversibility, the exact blast radius, that the platform deletes in the background after immediate disappearance from list_projects, that the confirm_name mismatch guard aborts with nothing deleted, and that a read-write token is required. This is precisely the extra behavioral context the annotations cannot carry.

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

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

Front-loaded with 'Destructive and irreversible' so the risk lands first, then scope, then the confirmation contract, then eligibility. Every sentence carries distinct information; the confirm_name sentence slightly overlaps the schema but reinforces the abort behavior.

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

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

For a 2-parameter destructive tool with an output schema and full annotation coverage, nothing an agent needs is missing: risk, blast radius, async side effects, the abort condition, auth requirements, and the sibling alternative are all present.

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, and the description mostly restates confirm_name. It does add marginal value by framing the mismatch guard as an atomic failure ('nothing is deleted') and tying project_id/confirm_name to list_projects as the source of truth, but it offers no format or syntax detail 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?

States a specific verb (deletes) and resource (a WHOLE project, by project_id) and enumerates exactly what goes with it: commits, deployments, hosts, volumes, restore points, managed database, bucket, and source repository. It explicitly contrasts with the sibling delete_commit, so an agent can distinguish destructive-scope variants without opening schemas.

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

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

Gives an affirmative condition (a project the user asked for by name, e.g. a test app or one made by mistake) and an explicit exclusion (never as cleanup the user did not ask for). It names the alternative for the narrower case: delete_commit, to remove one commit and keep the 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?

Goes well past the destructiveHint annotation by describing the concrete blast radius: the live site stops serving on its stable host, no replacement canonical is picked, yet the release stays reachable at its per-commit URL. It also discloses the read-write token requirement and idempotent no-op reporting, all of which the annotations alone do not convey.

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

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

Impact on the live site is front-loaded and every sentence carries information, including the guardrail routing. It is dense and em-dash heavy, and the no-op and token notes could be ordered more crisply, but there is no filler.

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

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

For a destructive, single-parameter mutation with an output schema covering return values, the description supplies the consequences, prerequisites, and side effects an agent needs. Nothing material about invoking it correctly is missing.

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

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

Schema coverage is 100% and the single job_id parameter is already documented with its source (list_deployments) and the no-op constraint. The description reinforces 'by job_id' and the canonical prerequisite but adds no format or sourcing detail the schema lacks, so 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?

States a precise verb and object: clearing a project's canonical (production) pointer by demoting the commit holding it, keyed by job_id. It distinguishes itself from promote_commit and from stop_commit/delete_commit by naming exactly which behavior it performs on the canonical pointer.

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 frames the tool as 'the unblock for every canonical guardrail', naming the three siblings that refuse the canonical commit, and states the no-op condition when the commit isn't canonical. Nothing an agent needs in order to choose this over stop_commit or delete_commit is left implicit.

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

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

Goes well beyond annotations (which only say destructive/openWorld/not-idempotent) by disclosing cost ('about two minutes' per commit+build), refusal behavior (server entrypoint on static preset is refused unless framework is passed on the same call), failure semantics (sha256 mismatch aborts the entire call before anything is committed), token requirements, and the temporary 72h project outcome with expires_at. It also states side effects on drafts ('a running draft keeps running afterwards') and privacy of dev_url — exactly the kind of context annotations cannot carry.

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

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

The first sentence is well front-loaded, but the body is a dense, semicolon-chained block that mixes deploy mechanics, preset taxonomy, provisioning, sha256 verification and return fields in one unbroken paragraph. Several clauses (S3_* env var list, the long parenthetical list of 15 alternate presets) are heavy relative to what an agent needs to select and call the tool. Valuable content, but it would be more usable split into short sections.

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 7-parameter destructive mutation with an output schema and annotations, the description covers the missing pieces: timing/cost, failure modes, prerequisites (read-write token), side effects, and creation-mode caveats. Return values are summarized at a level consistent with the output schema rather than duplicating it.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining the create-vs-update contract (omit app_id for new + app_name required; pass app_id and send only changed files plus delete_paths), the Conventional Commits form of intent and that it becomes the timeline message, and the preset-selection logic behind framework. It still repeats some schema text rather than adding new semantics for every field, so it lands just 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?

Opens with a specific verb+resource pair: 'Creates an app from source files, or commits and builds a change to one', which cleanly covers both the create and update modes. It explicitly distinguishes itself from the nearest siblings by naming sync_files and publish_draft as the draft-editing path. An agent can tell this apart from deploy_project or redeploy without opening a schema.

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

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

Explicit when-to-use routing: 'For an edit to an existing app on any preset with a draft runtime, use sync_files first, then publish_draft for one commit', plus 'iterate with sync_files ... call this once with the final files, not once per small edit'. It also gives a decision rule for preset choice (static default, fastapi when an API/DB/uploads are needed) and for app_id vs app_name. Exclusions and alternatives are both present.

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

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

Beyond annotations, the description discloses a required read-write token (an auth prerequisite not encoded anywhere in structured fields) and that the call returns job_id and attempt_id suitable for polling. It doesn't cover retry behavior or what duplicate triggers do, but the annotations already flag non-idempotent, open-world behavior.

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

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

Three tight sentences: purpose first, target resolution second, return value and auth third. Every sentence carries information and nothing is padded.

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

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

With an output schema present and 100% schema coverage, the remaining gaps are small: the description covers the action, defaulting behavior, the follow-up polling tool, and the auth requirement. The one missing piece is any statement of how this differs from redeploy or deploy_files.

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 description's commit/ref defaulting language largely restates what the schema already says (commit defaults to tip of ref; ref defaults to the project's configured ref). No additional format or syntax detail is contributed beyond the schema, so 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?

States a specific verb and resource: "Trigger a build + deploy for a project," plus the resolved target semantics (given commit, else tip of ref). An agent immediately knows what the tool does. It does not, however, distinguish itself from nearby siblings like redeploy or deploy_files, which likely have overlapping intent.

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

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

Usage is only implied — you call it when you want to build and deploy. The one real routing hint is "poll with get_build_status," which helpfully names the next tool. There is no explicit when-not guidance or comparison against redeploy/deploy_files, so the alternative selection is left to inference.

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

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

Goes well beyond the annotations: row/byte caps, per-statement timeout, 25-statement limit, single-transaction all-or-nothing semantics, tenant credentials rather than admin, return shapes, and which statements are irreversible. Annotations already flag destructiveHint, and the description reinforces rather than contradicts 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?

Front-loads the core action and scope, then layers limits, credential behavior, return values, and routing in dense, waste-free sentences. No sentence is filler given the safety-critical nature of the tool.

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

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

Covers everything an agent needs for a destructive write tool: limits, transactional semantics, execution identity, return shape, irreversibility, and credentials recovery. The output schema exists, yet the description's brief return-value note still adds useful confirmation.

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, and the description mostly restates the same transaction/irreversibility notes found in the sql field description. It adds no new parameter-level detail such as SQL dialect caveats or size limits per parameter, so 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?

States a specific verb and resource (write SQL against the project's managed PostgreSQL database) and enumerates the statement classes covered (INSERT, UPDATE, DELETE, DDL). It explicitly distinguishes itself from the read sibling query_sql, so an agent can choose without opening either schema.

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

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

Gives an explicit alternative for the opposite case ('For reads, use query_sql') and a recovery path ('If the tool reports lost credentials, provision_postgres repairs them'). It also names a prerequisite (requires a read-write token), so both routing and gating are covered.

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

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

Beyond the annotations (destructiveHint, idempotentHint, non-read-only), the description discloses concrete behavior: private-by-default creation, a 302 /unauthorized response for non-owners, refusal for structurally authentication-gated apps, and a read-write token requirement. These are operationally decisive facts an agent could not infer from the annotation block.

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

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

The core action and the public=false reverse case are front-loaded in the first sentence, and each subsequent sentence carries a distinct constraint (default privacy, sibling exclusions, refusals, auth). It is dense but no sentence is pure filler; the dashboard-pill analogy is the only soft clause.

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 three-parameter mutation with an output schema, the description covers what an agent needs: defaults, reversibility, response behavior for non-owners, auth requirements, and refusal conditions. Nothing material is left for the agent to guess before calling.

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, but the description adds meaning: it pins the default of public to true and frames it as a publish/unpublish switch, and reinforces job_id as the target commit. The project_id ownership constraint is left to 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 states a concrete verb and resource ('publish a commit... or take it back to owner-only with public=false') and explains the mechanism ('same as the dashboard's private/public pill'). It further separates the tool from update_settings and redeploy by naming what those do instead, so an agent can place it among siblings without opening schemas.

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 a clear triggering condition: commits ship private, and a link meant for someone else 'needs this first', with public=false as the reverse case. It also rules out two alternatives explicitly ('update_settings default_public only governs commits created later; redeploy does not change visibility'), though it does not contrast with the similarly named promote_commit/demote_commit 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context on top: the reply always self-identifies the commit and its canonicality, and during a rollback the returned commit/state are explicitly non-final and possibly unrestored. That is exactly the kind of caveat an agent cannot infer from structured fields.

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

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

Front-loaded with the field inventory, then the commit-selection caveat, then the rollback caveat — a sensible ordering. It is dense and the canonical-commit caveat is stated twice (in the commit sentence and again in the rollback sentence), costing a little economy.

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, yet the description goes further by flagging that the payload self-describes its commit and can carry a rollback object whose data may not be final. For a two-parameter read tool with full schema coverage and annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description still reinforces the non-obvious semantics of commit: the fresh deploy_files commit isn't canonical, so the default answers about the version production still serves. It adds interpretive value beyond a bare field description rather than merely restating types.

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

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

The description opens with a specific verb+resource ('Live deployment status of a project') and enumerates exactly what comes back: state, commit, deploy URL, build status, pod readiness, restart count, start time. It also draws a boundary with get_rollback_status, so an agent can distinguish it from adjacent status tools without opening a schema.

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

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

It states clearly when the default applies (canonical/production commit) and when to override it (pass commit to ask about a specific one), including the concrete post-deploy_files pitfall. It doesn't explicitly route the agent between this tool and get_build_status or probe_app, so it stops short of full alternative 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, idempotentHint, openWorldHint=false and destructiveHint=false, so safety and side-effect questions are answered structurally. The description adds real behavioral context beyond that—this returns an informational contract rather than live state, and passing project_id switches from generic schema to concrete filled-in examples. It still does not say whether values reflect the current deployment or a static reference.

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 resource definition before the parameter caveat, with no filler. The dense enumerations (var names, static vs server frameworks) each carry information an agent needs.

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 shape need not be described, and the description still conveys the useful distinction between build-time and runtime var sets. Given one optional parameter and full annotation coverage, what remains missing is minor—mainly whether the contract is current-state or documentation.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline of 3 applies. The description's phrasing closely mirrors the schema wording ('fill in concrete example values from that project's canonical commit') rather than adding new semantics such as what 'canonical commit' resolves to.

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 resource—the environment contract kad.dev injects into builds and running pods—and enumerates its contents (BUILD_COMMIT full SHA, BUILD_COMMIT_SHA short SHA, user-exposed vars) plus how static vs server frameworks consume them. That is far more concrete than a tautological restatement of the title, though it never contrasts itself with adjacent read tools like get_settings or get_build_logs.

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

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

Usage is only implied: the agent can infer this is a read-only reference lookup, and the optional project_id hints at when concrete values are wanted. There is no explicit when-to-use / when-not-to-use and no named alternative for configuration questions that belong to get_settings or set_env_vars.

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 readOnly/idempotent/non-destructive, so the safety bar is low. The description adds the useful fallback behavior (latest attempt) and that output is per-step, but that fallback is also in the schema and the return shape is 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?

One tightly packed sentence; the resource and key come first, the purpose clause second, and the default behavior last. Nothing wasted.

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

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

With a full schema, rich annotations, and an output schema, the definition covers what an agent needs to call it correctly. Only a pointer to sibling log/status tools would improve it further.

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 both parameters are documented there, including the attempt_id default and the list_deployments provenance for job_id. The description only restates these, adding no format or syntax 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?

States a specific resource ('per-step build log output for a deployment') and the key ('by job_id'), plus the diagnostic intent. It implicitly separates itself from get_runtime_logs by saying 'build logs', but never names the sibling explicitly.

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?

'used to diagnose a failed build' gives a clear use context and the default-to-latest-attempt behavior tells the agent the common-case invocation. No explicit when-not or alternative (e.g., get_runtime_logs for runtime issues, get_build_status) is offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations, notably PENDING queue_position semantics and the polling expectation.

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

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

The description is a dense, front-loaded sentence with no wasted phrases. It prioritizes the resource, the returned status details, and the important PENDING polling behavior.

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

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

With an output schema present, the description need not document return values, yet it still highlights key status semantics such as failure diagnosis and PENDING queue behavior. For a one-parameter read-only status tool with full annotations, this is complete enough.

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 job_id parameter is already documented in the schema as coming from list_deployments. The description only restates 'by job_id' and adds no extra format or sourcing detail beyond the schema, so 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 states a specific verb and resource: build status of a deployment by job_id. It also enumerates the returned status facets, making it clearly distinct from sibling status tools like get_app_status, get_plan_status, or get_build_logs.

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

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

It provides clear usage context: call it with a job_id to inspect a deployment build and keep polling when the result is PENDING. It does not explicitly exclude alternatives such as get_build_logs or get_app_status, but the context is sufficiently 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 readOnlyHint/idempotent annotations, it discloses the full status vocabulary with semantics (approved vs applied vs failed, expired TTL), that approval in the dashboard is what executes the action, and that retry_after_s presence/absence signals terminal vs polling state.

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?

One dense paragraph, but front-loaded with the purpose and alternatives before the status enumeration. The inline list of eleven tool names is heavy yet functional since it defines scope precisely; little else could be cut without losing routing 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?

Output schema exists, yet the description still explains the possible statuses and the meaning of retry_after_s, and it covers the lifecycle gap (no apply call). 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?

Schema coverage is 100%, so baseline is 3, and the description adds contextual meaning by tying plan_id to the specific gated calls that return it. It does not add format details or error conditions for the id, so it edges just 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?

States a specific verb and resource ('read the current outcome of a gated write tool call') and enumerates exactly which calls park pending approval. It is clearly distinguishable from await_plan and from the write siblings it reports on.

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

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

Explicitly says to use this when a gated call returned pending_approval, names await_plan as the blocking alternative and states when to prefer each, and preempts a likely misuse by declaring 'there is no apply call'. Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine context the annotations cannot: what each entry contains and that an empty list is a legitimate no-data state rather than an error.

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

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

Three sentences, front-loaded with the core purpose, no filler. The middle sentence enumerating returned fields partly overlaps the output schema, which is the only mild 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?

An output schema exists, so return values need not be explained, and the empty-state caveat is a useful addition. The one real gap is ranking: 'popular' implies an order but the description never states that results are sorted by project count.

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 single limit param documents itself with a default of 50), so the baseline is 3. The description never mentions limit or how ordering interacts with truncation, adding nothing 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?

States a specific verb (lists) plus a precise resource (npm packages most often declared by kad.dev projects) and scopes it to a population. No sibling tool covers package data, so an agent can distinguish it immediately from the project/deploy/file 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?

Usage is only implied by the resource description; there is no statement of when to reach for this versus something like list_objects or query_sql, and no guidance on how to pick a limit. The empty-result note hints at data availability but is a caveat, not a when-to-use rule.

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

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

Annotations already declare read-only, idempotent and non-destructive, and the description still adds substantial context: it decodes each status value, explains what 'failed' means (stopped, will not continue), names the diagnostic fields, gives polling semantics via retry_after_s absence meaning final, and notes the read is from stored state so a dropped call or timeout loses nothing. That last point is exactly the reassurance an agent needs for a polling loop.

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

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

Front-loaded with the core purpose and the rollback_id-vs-project_id routing, which is the highest-value information. The middle is a dense run-on enumerating statuses and failure fields that could be trimmed, but nearly every clause carries actionable meaning.

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

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

Even though an output schema exists and return values need not be explained, the description covers status states, failure semantics, polling cadence and the wait_s blocking tradeoff. Nothing an agent needs to call this correctly or interpret a failure is missing.

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

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

Schema description coverage is 100% and the schema text for wait_s, project_id and rollback_id is near-identical to what the description says, so the description adds little parameter meaning beyond restating it. Baseline 3 is correct 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?

States a specific verb and resource ('progress and final result of a rollback') and immediately distinguishes the two lookup modes, rollback_commit for starting vs this tool for polling. An agent can separate it from rollback_commit, get_app_status and get_build_status without opening any schema.

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

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

Explicitly routes the caller: use rollback_id when you have it from rollback_commit, use project_id when the reply was lost or the rollback came from the dashboard or an approved plan. It also explains when to use wait_s versus returning at once. It does not contrast with other status tools, but the selection guidance within the tool is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real value by explaining the log_drops signal and that gaps are expected under rate limiting — behavior an agent could otherwise misread as missing data. It does not mention pagination or result-size behavior, keeping it at 4 rather than 5.

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

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

Two sentences, zero waste, with the resource and ordering front-loaded and the edge-case caveat (log_drops) placed last where it belongs. Nothing is repeated gratuitously.

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, full parameter coverage, and rich annotations, the description carries only what structured data cannot: the truncation semantics. The one gap is the lack of routing guidance against get_build_logs, but overall an agent has enough to call this correctly.

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

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

Schema description coverage is 100%, so all six parameters (dev, level, limit, commit, job_id, project_id) are documented in the schema, including the commit/job_id precedence rule. The description only restates the commit default and level filter, adding no syntax or format detail beyond the schema — baseline 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?

States a specific verb and resource ('runtime (stdout/stderr) log lines for a project') plus ordering ('newest first'), which implicitly but clearly separates it from the sibling get_build_logs. An agent knows exactly what this returns without opening the schema.

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

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

It gives the default scope ('canonical commit') and an optional level filter, so the default usage path is inferable, but it never states when to pick this over get_build_logs or when the dev flag path is appropriate. No explicit exclusions or when-not guidance.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, but the description goes well beyond them: it discloses that secret-looking values are masked unless reveal_secrets=true AND the token is read-write, that read-only tokens always get masked values, and that masked values still work at runtime because the variable is injected into the pod. That is exactly the non-obvious operational context an agent cannot infer from structured fields.

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

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

The content is front-loaded with the field inventory followed by the two constraints that matter (database/storage markers, then masking). It is slightly repetitive — the 'a masked value is not a problem' point is argued twice across the final two sentences — but every sentence carries real information.

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

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

An output schema exists and annotations declare the safety profile, so the remaining burden is behavioral — auth-dependent masking and how env vars reach the app — which the description covers thoroughly. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% and the reveal_secrets schema entry already documents masking and the read-write token requirement, so the description is largely restating structured data. project_id gets no additional meaning beyond the schema's 'from list_projects'. Baseline 3 applies when the schema does the heavy lifting.

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 precisely enumerates what the tool returns — repo, ref, framework, port, build commands, health-check path, canonical host, sub-path, output dir, env vars, and managed database/storage markers — so an agent knows exactly what resource this reads. It never contrasts with nearest siblings like get_build_env or update_settings, so differentiation is left to the name and title.

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 statement of when to call this versus alternatives such as get_build_env, get_app_status, or list_projects, and no exclusions. The only workflow hint is indirect — a note in the schema that set_env_vars merges so reading isn't needed to write — which is not a 'use this tool when' instruction.

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/idempotent annotations, it discloses non-obvious semantics: newest-first ordering, that state is the commit's runtime state now and 'unknown' means the cluster could not be read, and the crucial caveat that a succeeded build_status does not mean the commit is running. It also explains the conditional rollback object and that its states can still change – behavior an agent could not infer from annotations or 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?

Front-loaded with the resource and ordering, and every sentence carries real information (field semantics, follow-up tool routing, rollback caveat). The opening field enumeration is partially redundant with the existing output schema, which keeps it just short of a 5.

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

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

For a read-only listing tool with a single fully documented parameter and an output schema, the description supplies exactly the missing semantic layer: what build_status vs state mean, and how the response changes during a rollback. Nothing needed to call or interpret it correctly is absent.

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

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

Only one parameter, and the schema already documents project_id at 100% coverage including the 'from list_projects' provenance hint. The description says the history is 'for a project' but adds no syntax, format, or edge-case detail about the id, so 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?

States a specific verb and resource ('per-commit deployment history for a project') plus ordering ('newest first'), and enumerates the returned fields, which separates it from get_build_status, get_app_status, and get_runtime_logs at a glance.

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

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

Explicitly routes follow-up actions ('Use the job_id with redeploy / stop_commit / start_commit / promote_commit / delete_commit') and points to get_rollback_status for rollback completion. It gives clear context but does not state when to prefer this over siblings like get_build_status or get_app_status.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine context beyond that: the backing store is private and never exposed, and the listing is limited to exact paths and sizes rather than content.

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

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

Three short sentences, front-loaded with scope and followed by the privacy constraint and the read_files alternative. No sentence 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?

The output schema covers return values, and the description handles scope, privacy and the content-vs-listing boundary. It is essentially complete for a simple one-parameter read tool, with only minor sibling differentiation left implicit.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds no further detail about project_id or its relationship to list_projects, which is acceptable at this coverage level.

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

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

States a specific verb and resource ('List the exact current source-file paths and sizes') and scopes it to apps created by deploy_files, which distinguishes it from generic listing siblings. An agent can tell this apart from read_files without opening either schema.

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

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

Explicitly routes content retrieval to read_files, giving a clear when-to-use-this-instead condition. It does not mention other nearby siblings such as list_objects, so the routing guidance is clear but not exhaustive.

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 read-only/idempotent/non-destructive safety profile, but the description adds genuinely new context: credentials come from the project's own managed store and never prompt the user, and results signal truncation when the object cap is hit. Return shape is also sketched, though pagination/resume behavior past the cap is not described.

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 resource and scope, then example and semantics, with no filler sentences. The parenthetical citations of provision_storage and the dashboard explorer are useful grounding rather than waste, though the paragraph is dense and could be broken up.

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 need not explain return values, yet it flags the truncation signal that matters for correct agent behavior. Scope, credential source, example usage, and the drill-down model are all covered for a two-parameter read 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 coverage is 100% and the prefix parameter description already states the delimiter and drill-down semantics, so the description largely restates the schema. It reinforces the intent but adds no format or edge-case detail beyond what the structured field 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?

States a specific verb and resource ('List objects in the project's managed S3 bucket') and anchors it to sibling tools by name ('the same bucket provision_storage created'). It is clearly distinguishable from list_files, which targets a different surface.

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

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

Explains how to use the prefix for folder drill-down and clarifies the one-level-deep listing model, which is real guidance. It stops short of explicitly naming when to prefer this over list_files, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds genuine value beyond that by disclosing the returned field set and spelling out the deployment state domain (running/crash/stopped/pending), which tells the agent what state vocabulary it will need to interpret.

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?

One sentence, front-loaded with the verb and resource, with the returned fields and state enum packed into the same clause. Nothing is padded and nothing important is deferred.

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

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

An output schema exists, so the description need not restate return structure; with no parameters and rich annotations, the only real obligation is telling the agent what scope of projects is listed ("the caller's") and what state values mean, both of which it does.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. It correctly does not invent parameter-like caveats (no filters, no pagination) that would need explaining.

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

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

States a specific verb ("List") plus a precisely scoped resource ("the caller's kad.dev projects") and enumerates what each record carries (canonical commit, deploy URL, framework, deployment state). This clearly separates it from siblings like list_deployments, list_files, or list_objects, which return different resource types.

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

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

Usage is implied rather than stated: with no parameters and a name/description that reads as an unfiltered list, the agent can infer this is the entry point for discovering projects. However, the description names no alternative tool and gives no conditions for choosing this over list_deployments or get_app_status when the agent wants deployment or status data.

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 (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: server-side host resolution from the project rather than caller input, the 2KB response truncation, redirect following, and a semantic enumeration of outcomes including the non-obvious 'auth_gate' case (private-commit 302/303 gate vs. Google sign-in). That is exactly the behavior an agent could not infer from structured fields.

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

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

The purpose and host-selection rules are correctly front-loaded, but a large share of the single dense paragraph enumerates return fields (host, host_kind, final_url, status, latency_ms, body prefix, redirect, outcome) that an output schema already declares. That duplication lengthens the read without adding selection value, and the wall-of-text format makes the outcome semantics harder to scan than a short list would.

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

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

For a 4-parameter read-only probe with an output schema, everything an agent needs is present: when to use it, how hosts are chosen, path constraints, alias precedence, and how to interpret each outcome class. Nothing material is left to inference.

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 already 100%, so the baseline is 3; the description goes beyond it by documenting alias behavior and precedence ('job_id wins if both are given'), by naming the source of each id (list_projects, list_deployments), and by stating the host is never taken from caller input. It does not add much for `path` beyond the schema, keeping it short of a 5.

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

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

States a concrete verb and resource ('Server-side HTTP GET against a project's OWN app as deployed on kad.dev hosting') and frames it as a smoke test the client cannot run itself. It is clearly differentiated from build/status siblings by the line 'A green build alone does not prove the app responds; this does.' An agent can pick between this, get_app_status, and get_build_status without opening any schema.

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

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

Explicit branching rules: no job_id → canonical production host; with job_id (sourced from list_deployments) → that commit's own host. It also names where the canonical host comes from (canonical_host in list_projects) and explains the precondition (client egress does not reach app hosts), so the agent knows exactly when this tool is the right call and when a direct fetch is not possible.

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 destructiveHint/idempotentHint annotations: it explains the prior canonical keeps running but loses its production URL, that guarded mode blocks for a verdict, that FAIL restores the candidate with no data lost, and that INSUFFICIENT_SIGNAL parks the run with no confirm tool available. These are exactly the consequences an agent needs before invoking a destructive, blocking operation.

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

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

Front-loaded with the state change and its side effect, then the mode branch, then the auth requirement. Slightly dense with nested parentheticals in the guarded sentence, but nearly every clause carries decision-relevant information.

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

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

For a destructive, potentially blocking mutation with an output schema (run_id/state/verdict are noted as returned) and full annotation coverage, the description supplies the missing behavioral context: what changes, what the old canonical retains, and how non-PASS outcomes are resolved. Nothing needed to call it safely is absent.

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

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

Schema coverage is 100%, so every parameter including the guarded-mode semantics is already documented, and the description largely recaps mode/expose rather than adding format or default detail beyond the schema. The one value-add is the census that mode is optional and that omitting it retains legacy behavior, which the schema also states.

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 (promote) and resource (commit) plus the precise resulting state: it becomes the project's canonical (production) deploy. The mention of the expose_commit alias and the contrast with demote_commit/expose_commit in the sibling list makes the boundary clear without opening another schema.

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

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

Gives concrete selection guidance for the main branching decision: use mode="guarded" to gate on an SLO canary, omit or pass "manual" for the instant flip, and states the read-write token prerequisite. It does not explicitly distinguish this from redeploy/rollback_commit/demote_commit, which is the remaining gap.

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

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

Adds substantial context beyond the annotations: idempotent short-circuit with already_provisioned=true, no-op on re-call, masked return values, env vars read from process environment at runtime, deployed commits rolled so the variable reaches running pods, and the read-write token requirement. This is exactly the mutation-and-side-effect detail the agent needs.

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

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

Front-loads the action and effect, then layers idempotency, return shape, rollout consequence, and auth in descending order of importance. Dense with zero filler despite several distinct claims.

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 purpose, idempotency, side effects on deployed commits, auth requirements, and return semantics; with an output schema present, nothing an agent needs before invoking 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 mode field is already fully self-documented in the schema (nas vs disk, omit for default, ignored on repeat calls). The description adds no syntax or format detail beyond that, so 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?

Specific verb and resource ('Provision the project's managed Postgres database'), plus the concrete effect of injecting DATABASE_URL. It draws a clear boundary against the alternative approach ('no external Postgres provider or pasted connection string is needed'), which separates it from set_env_vars and provision_storage.

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

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

Gives a strong usage signal by anchoring to a known UI action (Settings → Postgres) and stating the precondition of a read-write token. It does not name sibling tools (e.g. provision_storage, execute_sql) or state when not to use it, so it falls short of full when/when-not routing.

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

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

Goes well beyond the annotations: discloses exactly which env vars are injected, that a second call returns already_provisioned=true without creating anything, that deployed commits are rolled so the new vars reach running pods, that values are masked, and that a read-write token is required. The pod-rollout side effect is a significant consequence an agent would otherwise miss.

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

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

Front-loads the verb and resource, then layers idempotency, return shape, side effects, and auth in a logical order. It is dense but nearly every clause carries new information; only the dashboard-button analogy is arguably decorative.

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, yet the description still summarizes the return (already_provisioned flag, masked env var names) and covers preconditions, side effects, and idempotency. Nothing an agent needs to decide-and-call 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 schema itself documents both mode and project_id in detail, including mode's behavior on re-provisioning. The description adds no parameter-level semantics beyond that, so 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?

States a specific verb (provision) plus the exact resource (managed S3-compatible bucket + scoped access key) and names the concrete artifacts created. An agent can separate this from provision_postgres and upload_object purely from the description.

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

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

Gives a clear trigger — 'needed by anything that handles file uploads' — and a strong exclusion ('files belong in this bucket rather than in Postgres columns, no external S3 provider is needed'). It does not explicitly name provision_postgres as the alternative, so a 4 rather than a 5.

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

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

Goes well beyond the annotations by disclosing that files are not re-sent, the draft keeps running afterwards, the build must be followed with get_build_status, refusal conditions, and the read-write token requirement. The mutation and irreversibility implied by destructiveHint=true is contextualized rather than merely repeated.

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

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

Front-loads the core action ('Makes a draft live') before the details. The dense paragraph is long but nearly every clause carries operational information; a little tightening of the return-value list would help.

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 mutation semantics, prerequisites, refusal cases, post-call follow-up, and token requirements, and even summarizes the return payload despite an output schema existing. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters, but the description adds real meaning: 'intent' becomes the commit subject in the timeline and must describe the whole change in Conventional Commits style. This supplements rather than duplicates 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?

Names the specific verb and resource (publish a draft) and explains exactly what that means: committing all draft changes as one commit and starting a build. It explicitly distinguishes itself from deploy_files and sync_files, so an agent can route correctly without opening the schema.

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

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

States the conditions for use (draft running, or changes kept from a self-stopped draft), the refusals (no changes held, owner-approval projects), and names the alternative (deploy_files) for that excluded case. Both when-to-use and when-not-to-use are 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?

Although annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: READ ONLY transaction enforcement, a 500-row truncation limit, a 5-second statement timeout, tenant credentials, and the semicolon restriction even inside string literals. These are meaningful operational traits 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 dense and front-loaded: purpose first, then statement restrictions, then execution limits, then the execute_sql alternative. Every sentence adds operational value and there is no filler.

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

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

Given that an output schema exists, the description need not explain return values. It covers the critical invocation constraints, safety behavior, limits, credentials, and alternative tool, so an agent has everything needed 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 coverage is 100%, so the baseline is 3, but the description adds useful semantics for the sql parameter: exactly one statement, allowed starting keywords, trailing-semicolon-only rule, and the fact that semicolons inside string literals are also refused. It does not elaborate on project_id beyond what the schema already says.

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: run one read-only SQL statement against the project's managed PostgreSQL database and return rows. It also explicitly distinguishes itself from execute_sql, making sibling selection clear without opening schemas.

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 guidance and names the alternative: use execute_sql for INSERT, UPDATE, DELETE, or schema changes. The read-only scope and allowed statement prefixes further clarify appropriate use.

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

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

Annotations already declare this as a safe, read-only, idempotent operation. The description adds useful behavioral context beyond annotations: text is bounded, reads can be resumed, and binary content is never returned. The only minor gap is the use of 'next_offset' while the input parameter is named 'offset'.

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 tight sentences with no wasted language. It front-loads the core action and follows with the key constraints and sibling reference.

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 simple three-parameter schema, full schema coverage, annotations, and an output schema, the description is complete enough for correct invocation. It covers provenance of paths, bounded/resumable reads, and the binary-content limitation.

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 schema already documents paths, offset, and project_id. The description reinforces provenance by saying paths should come from list_files, but it does not add substantial parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: reading exact current source files. It also scopes the tool to an app created by deploy_files and distinguishes it from list_files by requiring paths from that sibling.

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

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

It gives clear usage context: use paths returned by list_files and target an app created by deploy_files. It does not explicitly state when not to use it or name alternatives beyond list_files, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real context beyond them: the two divergent execution paths (re-install release on last-deploy failure vs. roll the pod) and the read-write token requirement. It doesn't state whether a restart can interrupt in-flight traffic or what the returned job state looks like, but that is largely 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?

One front-loaded sentence that conveys the action, the non-rebuild constraint, the branch behavior, and the auth requirement with no filler. Nothing could be removed without losing 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 tool with an output schema and full annotation coverage, the description supplies the essential additions: token scope and the conditional restart semantics. The one material gap is sibling ambiguity with restart_app, which the description should resolve but doesn't.

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 single parameter is documented as "the deployment job id (from list_deployments)," so the schema carries the load. The description restates "by job_id" without adding format or sourcing detail, which lands at the baseline 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?

Specific verb + resource ("Restart a deployment") plus the mechanical detail that it happens "without rebuilding," which tells the agent what actually changes. It falls short of a 5 because it never distinguishes itself from the similarly purposed sibling restart_app, nor from rollback_commit, both of which could plausibly be chosen for a stuck deployment.

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

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

Usage is implied (restart a deployment by job_id) and one hard prerequisite is given—"Requires a read-write token." But there is no explicit when-to-use/when-not guidance and no routing to the obvious alternatives (restart_app, rollback_commit, stop_commit), so the agent must infer selection from the surface-level wording.

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

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

Adds substantial context beyond annotations: the exact mechanism (annotation bump), what is explicitly NOT touched (no helm upgrade, no env/Secret write, no image change), the precondition that a running deployment must exist, and the read-write token requirement. Minor gap: the 'safe restart' framing sits in mild tension with destructiveHint=true and idempotentHint=false, neither of which the description addresses (e.g. that re-invoking bumps the annotation again, and that pods briefly go down).

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

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

Front-loads the verb and mechanism, and every clause carries routing or safety information. Slightly overlong and repetitive in places — 'blast radius' and the redeploy contrast are asserted twice, and the parenthetical example could be tighter.

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 need not explain return values, and annotations plus 100% schema coverage carry the structured details. What remains — mechanism, preconditions, auth, sibling routing, and non-effects — is all covered, so an agent has everything needed 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 coverage is 100% and both parameters already document their source tools (list_deployments, list_projects), so the schema does the heavy lifting. The description restates the commit default to the canonical production commit but adds no format or edge-case detail beyond what the schema provides. Baseline 3 is correct.

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

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

States a specific verb and resource ('roll a project's pods for the canonical (production) commit') and defines the exact mechanism ('a pod-template annotation bump, exactly like kubectl rollout restart'). It explicitly names the sibling it is not (redeploy) and the sibling precondition tool (start_commit), so an agent can distinguish it without opening any schema.

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

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

Gives the positive selection criterion ('fits whenever the goal is just make the running pods pick up nothing new... e.g. clear an in-memory leak or a wedged process'), an explicit exclusion versus redeploy ('which re-runs the full release install'), and a routing rule for the failure case ('start it first with start_commit'). Nothing is left to inference.

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

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

Beyond the destructiveHint annotation, the description discloses that the call is asynchronous, returns immediately with a rollback_id, may take minutes, can destroy data in restore_data mode, stops the app/database during restore, leaves a safety copy, allows only one rollback at a time, and requires a read-write token. These are exactly the operational risks an agent needs before invoking 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?

The most important danger and async behavior are front-loaded, and nearly every clause carries operational value. However, it is a dense run-on paragraph, and breaking out mode behavior and status semantics would make it easier to scan.

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

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

For a destructive, asynchronous production operation, the description covers lifecycle, mode differences, irreversibility, status interpretation, refusals, and authorization. An output schema exists, so return-value details need not be repeated.

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% description coverage and already documents job_id, mode, and point_id in detail. The description reinforces job_id and mode semantics but does not mention point_id and adds little parameter-level meaning beyond the schema, 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 and resource: it STARTS a rollback of a storage commit v2 project's canonical production pointer to an earlier commit identified by job_id. It also clearly distinguishes the two modes and names related tools such as get_rollback_status and list_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?

It explicitly covers when to use each mode, including that keep_data is the safe default and restore_data destroys data. It also explains when to use get_rollback_status, what list_deployments and get_app_status can show mid-rollback, and when the tool refuses projects or commits.

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

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

Annotations declare destructiveHint=true and idempotentHint=true, and the description adds critical context beyond them: deployed pods are rolled, unlisted vars and secrets are preserved in merge mode, "***" payloads are rejected, and a read-write token is required. This is exactly the extra operational context annotations cannot convey.

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

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

Five tight sentences, front-loaded with the action and side effect, then merge semantics, deletion, the replace warning, and the token requirement. No filler.

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

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

A destructive, multi-mode mutation tool is fully framed: default behavior, dangerous mode, deletion path, auth requirement, and a rejection rule for masked input. An output schema exists, so return values need not be described.

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

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

Schema coverage is already 100%, so the baseline is 3. The description still adds practical meaning: merge vs replace semantics of envs, the merge-only restriction on delete[], and the platform-provisioned credential exclusion. It stops short of covering build_exposed, which is left entirely to the schema.

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

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

States a specific verb and resource (write a project's environment variables) plus the consequential side effect (roll the deployed pods). It is clearly distinct from sibling read tools like get_settings and get_build_env.

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 the default behavior (merge), when to use delete[], and a strong when-not rule: pass mode="replace" ONLY to wipe the whole set. It also warns against echoing back masked values from get_settings.

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

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

Adds substantial context beyond the annotations: a concrete rate limit (one per 10 minutes per project), an auth requirement (read-write token), and the fact that it captures the canonical production commit rather than a draft. These are operational facts the agent cannot derive from readOnlyHint=false / destructiveHint=false / idempotentHint=false 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?

Four short sentences, each carrying a distinct fact (action, dashboard analogue, plan availability, rate limit, auth), with the core action front-loaded and no filler.

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

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

For a single-parameter mutation tool with an output schema and annotation coverage, the description supplies everything an agent needs: scope, rate limit, token requirement, and plan availability. Return values are handled by the output schema, so nothing material is missing.

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

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

Only one parameter, and the schema already documents it at 100% coverage including the pointer to list_projects. The description's mention of 'a project's canonical commit' reinforces what the id selects but adds no new syntax or format detail, so the 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?

States a specific verb ('take a restore-point snapshot') plus the exact resource and scope ('a project's canonical (production) commit'), which cleanly separates it from siblings like promote_commit, deploy_project, or rollback_commit. The 'right now' framing makes the immediacy explicit.

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

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

Gives strong context for when to reach for it: the dashboard 'Snapshot now' equivalence, availability on every plan, and the one-per-10-minutes rate limit. It stops short of naming an alternative or exclusion condition (e.g., when to prefer rollback or promote instead), so it is not a full when/when-not pair.

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, idempotentHint=true and destructiveHint=false, and the description adds context those hints cannot: the release is reinstalled from the already-built cached image with no rebuild, and nothing is destroyed. It also surfaces the read-write token requirement, which the annotations do not encode.

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?

One front-loaded sentence carries the action and mechanism, followed by two short clauses covering the inverse relationship and the anti-use-cases. There is no repetition of the title and no filler.

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

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

For a single-parameter mutation with full annotation coverage and an output schema, everything an agent needs is present: input source, no-rebuild semantics, token requirement, and sibling disambiguation. Return values need not be described because the output schema covers them.

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 job_id property already explains that it comes from list_deployments and restarts a stopped commit from the cached image. The description's 'by job_id' adds no syntax, format or provenance beyond that, so the baseline 3 for a fully documented single parameter 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?

States a specific verb (start) and resource (a previously stopped per-commit deployment) and anchors it to a familiar UI action (dashboard Actions → Start). It explicitly names what it is not (deploy_project, delete_commit) and what it inverts (stop_commit), so an agent can separate it from all relevant siblings without opening a schema.

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

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

Gives the positive condition (a stopped per-commit deployment, identified by job_id), the explicit alternatives and when they apply (deploy_project for a new build, delete_commit when destruction is intended), and a prerequisite (read-write token). This is exactly the when/when-not/alternatives structure an agent needs.

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

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

Annotations declare destructiveHint=true, and the description disambiguates precisely what that means here: pods are torn down while Helm metadata, DB rows, artifacts, volumes and data survive, and the change is reversible. It adds what annotations cannot — side effects, the production-commit refusal, the read-write token requirement, and the contrast with permanent deletion.

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

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

Front-loads the highest-risk fact ("Affects the live site") and organizes the rest as what is kept, what is removed, contrast with delete_commit, and preconditions. Dense but nearly every clause carries decision-relevant information; there is minor overlap with the schema's job_id text.

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 and full annotations are present, and the description still covers everything an agent needs before invoking: impact on the live site, reversibility, what is preserved, the sibling contrast, the production exclusion, and the token requirement.

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 single job_id parameter already documents its source (list_deployments), reversibility and the canonical-commit refusal. The description largely restates the same facts rather than adding new argument-level detail, so the 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?

States a specific verb and resource ("Stops a per-commit deployment (by job_id)") and immediately maps it to a familiar equivalent (dashboard Actions → Stop). It explicitly distinguishes itself from two siblings, delete_commit and start_commit, so an agent can route without opening schemas.

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

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

Gives explicit when-to-use (stop rather than delete), the alternative (delete_commit for permanent removal, start_commit to restore), and a hard exclusion (the canonical/production commit is refused, promote another first). Nothing about selection is left to inference.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description adds the critical missing context: exactly what is destroyed (uncommitted changes, including those retained from a prior automatic stop), the 30-minute auto-stop / 24-hour retention lifecycle, what is explicitly preserved (deployed app and commits), the auth requirement (read-write token), and the idempotent stopped=false 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?

Leads with the definition and effect, then the destructive scope, then the usage rule, then the safety boundary (deployed app untouched), then idempotency and auth. Sentences are dense but each carries distinct, decision-relevant information.

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

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

For a destructive one-param mutation with an output schema, the description covers everything an agent needs: what it does, what it irreversibly removes, what survives, when to prefer waiting for auto-stop, and what the result reports — the output schema handles return structure.

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

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

Only one parameter and the schema already documents it at 100% coverage ('the managed project id (from list_projects)'), so the description adds essentially nothing beyond the schema. Baseline for a fully-covered single-param schema is 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?

States a specific verb and resource ('Stops a project's draft') and defines the resource inline as 'the running copy that sync_files fills,' immediately disambiguating it from deployed artifacts and from siblings like publish_draft or stop_commit. It also names the concrete effects (removes pod and dev_url).

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

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

Gives explicit when-to-use conditions ('when the user wants the draft and its unsaved changes gone, or to free one of the 3 draft slots') and an explicit when-not ('It is not routine cleanup: a draft stops by itself after 30 minutes...'), so the agent knows the automatic alternative and doesn't need to call this tool for idle drafts.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantial context the annotations cannot convey: writes stay in the draft and are not live or saved, drafts stop after 30 minutes of inactivity and keep files 24 hours, an owner-initiated stop discards unsaved files, dev_url is private unless the draft is public, and a read-write token is required. The sha256 fail-before-apply contract is also stated explicitly.

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

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

The purpose is front-loaded correctly, but the remainder is one dense paragraph covering draft lifecycle, visibility defaults, Google-login edge cases, 72h projects, publish guidance and sha256 behavior. Nearly every sentence carries operational value, yet the lack of structure makes it hard to scan and several advisories arguably belong with publish_draft or get_app_status.

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, stateful mutation on a temporary runtime, the definition covers start/stop/restore behavior, failure modes, token requirements and next steps; with an output schema present it does not need to explain return values. An agent has enough to call this correctly on the first attempt.

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 a little on the `data` parameter (copy vs empty, a running draft keeps its earlier choice, copy seeds DB/app files and reads the bucket live) and on per-file sha256 verification, but that largely restates what the schema descriptions already say.

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

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

The opening sentence gives a specific verb and resource ('Edits an app's draft: writes files into a temporary running copy') and immediately delimits it against deploy/build semantics ('WITHOUT a commit or a build'). An agent can distinguish it from deploy_files, publish_draft and start_commit from the first line alone.

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

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

It enumerates the runtimes where the tool applies (static, vite, react ... configured sanic presets), the exceptions requiring flags (go, rust, spring-boot), the runtimes with no draft runtime (dockerfile), and the retry path ('Start can return starting: retry sync_files'). It also routes the agent to publish_draft once the user is satisfied, explaining why ('a commit per small edit fills the timeline').

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

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

Beyond annotations, the description details when changes take effect: build settings apply to the next build, port and health_check_path restart the running app, storage_mount_path applies on the next deploy, and sign-in gate changes apply immediately. It also clarifies that existing commits keep their visibility and that removing an allowed email address ends access on the next request.

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?

Despite being a long description for a 17-parameter mutation tool, it is front-loaded with the core partial-update contract and organized into clear paragraphs for build settings, visibility, sign-in gate, and environment-variable exclusions. The sentences carry operational information rather than filler.

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

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

With annotations present, an output schema available, and 100% schema description coverage, the description still adds the important behavioral context: partial-update semantics, field-specific timing, visibility effects, sign-in gate behavior, env-var exclusion, and authentication requirements. Nothing material appears missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field meaning by grouping parameters and saying omitted fields keep their current value. It also reinforces effect timing for groups such as build settings versus live sign-in gate settings, though much of the per-parameter detail already exists in the schema.

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

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

The first sentence states a specific verb and resource: 'Change the settings of one project.' It also distinguishes the tool from set_env_vars by explicitly reserving environment variable changes for that sibling.

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

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

It explains the partial-update contract directly: send project_id and only fields to change, with omitted fields retaining current values. It also names an explicit exclusion and alternative ('Environment variables are not changed by this tool; set_env_vars does that') and states the read-write token requirement.

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

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

Goes well beyond the annotations by disclosing the destructive behavior in plain language ('silently OVERWRITTEN'), the per-file size limit, the managed-credential model ('never asks the user for a key'), and the fact that binaries don't land in Postgres. These are exactly the side effects an agent needs to reason about a destructiveHint write.

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 critical facts (destination, overwrite risk, size limit) are front-loaded, but the 'same reach the dashboard's Object storage explorer gives the owner' clause and the 'never stores binaries in Postgres' aside are padding at the edges of a five-sentence 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?

With an output schema present and full parameter documentation, the description only needs to cover side effects and preconditions, and it does — overwrite semantics, auth level, and credential handling. The unquantified 'Per-file size limit applies' is the one gap an agent might trip on.

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 much of the description's parameter prose (base64 encoding, extension sniffing for content_type, the key example) restates what the schema already documents. It adds no syntax, constraint, or format detail beyond the schema, so the 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?

States a specific verb and resource — 'Upload one file into the project's managed S3 bucket' — and situates it as 'the write half of the object-storage tools', which separates it from list_objects, read_files, and sync_files at a glance.

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?

Names the relevant sibling (list_objects) as the way to inspect an existing key before overwriting, and states the auth prerequisite ('Requires a read-write token'). It doesn't give an explicit when-not or a rule for choosing between upload_object and deploy_files/sync_files, so it falls short of a 5.

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