lavela

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

Annotations already declare readOnlyHint=true, and the description adds genuinely new context: the call is free, and `nextActions` contains links the USER opens versus tools the agent may call (a real behavioral distinction). It stops short of documenting auth requirements or rate limits, and the 'read-only' restatement is redundant with the annotation.

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

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

The call-first instruction is front-loaded, which is good, but the body is a dense run-on chain of field definitions and arrows that is heavy for a zero-parameter read tool. Much of it restates what the output schema already carries, so several sentences do not fully earn their place.

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

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

With no inputs, an output schema present, and annotations covering the safety profile, the description supplies the remaining decision context: when to call, how to read the money fields, and where the docs live. It lacks only sibling routing (e.g., versus get_status or project_overview) to be fully complete.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly spends no effort on nonexistent inputs and instead explains output semantics.

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

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

The description states what the tool reports — account standing, credit and balance — and the title reinforces this. It is distinguishable from siblings like get_status or project_overview, but it never uses a crisp verb+resource formulation; 'Where the account stands' requires inference. Purpose is clear but not maximally sharp.

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 timing is given: 'call it first, before paid compute and after any wallet/trial/cap error.' It also steers a decision rule ('decide from it and `wallet`, not `billingMode`'). What is missing is any named alternative tool for the cases where this one is not the right call.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered; the description reinforces with 'Free, read-only' and adds the private-repo auth dependency on connect_github. It also sketches the return concept (lane + why). Useful added context, though it stops short of describing scope limits or analysis depth.

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 verb and target, and the sequencing/private-repo facts are packed efficiently. Slightly dense with parenthetical lane definitions, but no sentence is wasted.

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

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

With no output schema, the description carries the burden of describing returns and does so concretely (framework, language, package manager, database/email, lane, one-line why), plus the call-ordering and auth prerequisites. 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 description coverage is 100%, with branch and subdir already richly documented (slash-containing branch caveat, monorepo probes). The description adds no parameter 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?

States a specific verb ('Inspect a GitHub repo') and enumerates exactly what it detects: framework, language, package manager, database/email use, plus the `lavela` lane with a one-line `why`. This is clearly distinguishable from siblings like provision_* or launch_saas, which act on the repo rather than analyzing it.

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

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

Explicitly routes usage with 'Call it before lavela.launch_saas' and gives a precondition for private repos ('work after lavela.connect_github'). Both the when-to-use and the prerequisite are stated, leaving nothing 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 only declare readOnlyHint=true, but the description adds substantial behavior: it opens the URL, validates a real page rather than a bare 200, is free, and wakes a sleeping server that gets billed as awake. This wake-and-bill side effect is exactly the kind of context the agent needs to invoke it responsibly.

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 question ('Is the live app up right now?') and then packs in scope, behavior, and cost. The parentheticals are dense but each carries distinct, useful information; only marginal tightening is possible.

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 no output schema, the description still explains what is reported (whether a real page is served) and covers cost and side effects. The single parameter is left unexplained, which is the only notable gap for this simple one-param tool.

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

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

Schema description coverage is 0% and the description never mentions projectId or its format, so it adds no semantic meaning beyond the schema. For a single, self-evident project selector the omission is minor, keeping this at a minimum-viable 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: checks whether the live app is up by opening its URL and reporting whether it serves a real page, not just an HTTP 200. The scope is unambiguous, but it never names a sibling (e.g., get_status, project_overview) to distinguish itself by name, so differentiation relies on inference.

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 clear context for use: it is free, wakes a sleeping server (billed as awake), and is the only place servers are checked since the monitor covers only web-hosting sites. It stops short of explicit when-not-to-use guidance or naming alternative tools for overlapping 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 only cover the safety profile (mutating, idempotent, non-destructive). The description adds the traits that matter: a running server 'restarts once', the change is persistent ('Later redeploys keep the choice'), the billing model for each state, and the precise error codes returned when preconditions fail.

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 verb and resource, and nearly every clause carries distinct information (pricing, preconditions, error codes, persistence). It is a single dense run-on paragraph with parenthetical error codes, which slightly hurts scannability but avoids redundant filler.

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

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

For a 2-parameter, no-output-schema mutation tool, the description covers everything needed: preconditions, exclusions, restart side effect, cost implications, and error signaling. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters including pricing tiers, so the baseline is 3. The description adds meaning beyond that by flagging the need to confirm the costlier alwaysOn=true setting with the user and by explaining what sleeping versus always-on state implies operationally.

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: 'Switch a server ... between always on ... and sleeping when idle', and immediately scopes it as 'in place: no rebuild'. That distinguishes it from rebuild/lifecycle siblings by clarifying no rebuild is needed and only a single restart occurs.

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 (avoid wake-up delay vs. save cost while asleep), explicit when-not (database/cache servers never sleep — 'stop them'), and preconditions ('A stopped or paused server must be started first (SERVER_STOPPED)', refused during builds). It even flags the human-in-the-loop requirement: 'confirm with the user before turning it on'.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this ('Free, read-only') while adding substantial context the annotations cannot carry: build duration, the ~20s wait ceiling, the meaning of a non-empty `error` on an 'ok' build, and the specific refusal codes (TRIAL_*, INSUFFICIENT_*_BALANCE, *_CEILING) that mean the build never ran and there is nothing in the code to fix.

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

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

Front-loaded with purpose, then usage, then error-code interpretation, then the rebuild pointer — a sensible order. It is dense with backticked codes and parentheticals, and the trailing docs URL plus the long code list push it toward the verbose side, but nearly every clause carries operational 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?

There is no output schema, so the description must carry the return semantics itself — and it does, enumerating the status values, the warning interpretation, and the refusal codes with their meanings and remediation. Combined with the cadence guidance, an agent has everything needed to poll correctly and interpret every outcome.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns an extra point by spelling out the routing logic between buildId and the projectId+service pair ('No buildId? Pass projectId (+ service)'), which is the one parameter decision an agent actually has to make. It stops short of documenting the wait values 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?

States a specific verb and resource ('Check a repo build') and immediately enumerates the three possible outcomes (building/ok/failed), so the agent knows exactly what this returns. It also names the sibling that performs the write action (lavela.compute_rebuild), cleanly separating this read-only check from the rebuild path.

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 covers the no-buildId fallback ('Pass projectId (+ service)'), the calling cadence ('builds usually take 3-6 minutes; each call waits up to ~20s — keep calling; don't start another build meanwhile'), and the only sanctioned way to re-trigger a build ('Build again only with lavela.compute_rebuild'). Alternatives and prohibitions are both stated, not implied.

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

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

Annotations only give readOnlyHint=false and destructiveHint=false, so the description carries the real burden and delivers: a stopped server stops answering within minutes and requests no longer wake it, billing stops but disk is still charged, and stopping is non-destructive unlike destroy_compute. These are exactly the operational consequences an agent cannot infer from 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?

Front-loads the core action and resource in the first clause, then layers usage, alternatives, and timing/billing in tight sentences. Every sentence earns its place; nothing is redundant with the schema or annotations.

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

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

For a 2-param, no-output-schema mutation tool, the definition covers parameter source, lifecycle timing, billing side effects, and how it differs from the sibling destroy/secret tools. No required context is missing.

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

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

With 0% schema description coverage, the description compensates for machineId by stating its provenance (from lavela.project_overview), which is genuinely additive. The action values are fully enumerated in the schema, so the description need not restate them, but it adds nothing beyond machineId's source.

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 set (start/stop/restart) plus the exact resource (a server) and the identifying parameter (machineId from lavela.project_overview). It also draws explicit boundaries against set_compute_secret (which already restarts) and destroy_compute (which removes), so an agent can distinguish it from 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?

Explicitly names when to use it ('restart a crashed server', 'start servers again after a top-up lifted a pause') and names alternatives with the conditions that select them (set_compute_secret for new secrets, destroy_compute for removal). This is a full when/when-not/alternative routing specification.

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

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

With only readOnlyHint=false, idempotentHint=false, destructiveHint=false in the annotations, the description carries the behavioral load well: it replaces the running server, refuses builds backed by sleeping database/cache, bills from the wallet (with a balance/pricing pointer), and preserves the server's size and always-on setting (with none running, the last values), noting always-on costs more. That is far more than the annotations 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?

The behaviorally important facts (original settings preserved, build id source, cost, confirmation) are front-loaded and every clause carries information, but the single mega-sentence with nested parentheses, em-dashes and mixed capitalization is hard to parse and would benefit from being split into two or three sentences.

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

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

For a 4-param mutation with no output schema, the description covers prerequisites, refusals, cost/auth (wallet), and override behavior, and points to docs for edge cases. It stops short of describing the immediate return (job id? server status?) or failure handling after the call, which an agent would want before invoking a paid, server-replacing operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: internalPort, subdir and gitRef override just that one setting, and subsequent rebuilds of the new build inherit the change. It also ties buildId to its source (lavela.compute_build_status) and explains the empty-string defaults implicitly.

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

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

States a specific verb and resource — 'Start a finished repo build again with EXACTLY its original settings' — and lists the preserved settings (branch, folder, port, env, mounts). It clarifies the workflow ('how a server lavela built from a repo is REDEPLOYED after a push or a fix'), but never names or distinguishes itself from the sibling tool lavela.redeploy, which an agent could easily confuse it with.

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 triggering context (after a push or a fix), a hard prerequisite chain (get the id from lavela.compute_build_status, only `rebuildable` builds), a refusal condition (sleeping database/cache refused), and an explicit instruction to confirm cost with the user before calling. Missing is an explicit when-not/alternative statement relative to lavela.redeploy or provision_compute_from_repo.

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

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

Annotations already declare readOnlyHint=true, and the description goes well beyond by decoding return states (`connected:true` = already done, `configured:false` = unavailable) and disclosing the retry workflow. This is meaningful behavioral context an agent needs to act on the result.

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

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

Extremely dense and front-loaded: purpose first, then the action, then the return-state branch, then the cost/safety note. No sentence is wasted.

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

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

With no output schema present, the description correctly compensates by explaining the returned fields (`url`, `connected`, `configured`) and what to do with them. Nothing an agent needs to invoke or interpret this tool is missing.

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

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

The tool takes zero input parameters, so the baseline is 4. The description's mention of `url`/`connected`/`configured` concerns outputs rather than inputs, so there is no parameter semantics to add.

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 (connect GitHub) and precisely describes the artifact produced: a browser link the USER opens. It is unambiguously distinct from siblings like connect_stripe or deploy_link, which it even names as a fallback.

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 triggering condition (a CONNECT_GITHUB build failure), the exact next action (hand over the url verbatim, then retry the deploy), and an alternative path (use a public repo or lavela.deploy_link) via the `configured:false` case. When, how, and alternatives are all explicit.

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

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

Annotations only supply readOnlyHint=false/destructiveHint=false; the description adds the real behavioral payload: this kicks off Stripe KYC (1-5 days), requires user confirmation, and that the onboarding link must be retrieved by polling lavela.get_status. It also clarifies that a 'choice_required' result is a no-op that started nothing, which prevents an agent from treating it as progress.

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 purpose, then behavior, then the edge case, and the doc link trails at the end where it belongs. It is dense and slightly compressed (parentheticals, em-dashes) 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?

With no output schema, the description still covers the state machine an agent must handle (oauth failure fallback, choice_required semantics, KYC wait + status polling), which is the hard part. It omits what the call itself returns and any error surface, leaning on the docs link for that residue, so it is complete but not exhaustive.

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

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

Schema coverage is 50% (mode and projectId undocumented). The description compensates by defining the meaning and triggering condition of mode 'oauth'/'new', the role of reuseAccountId ('an accountId from a choice_required result's options', mode 'new' only), and forceNew:true as the always-create overwrite. Only projectId is left unexplained, hence not 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 the specific verb and resource ('connect their Stripe account') and immediately splits the two modes of operation ('oauth' vs 'new'), which is what an agent needs to tell this apart from connect_github and the other connect_* siblings.

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

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

Explicit when-to-use for every branch: mode 'oauth' to connect an existing account, mode 'new' as the documented fallback when oauth fails, and for a 'choice_required' status it names the two alternatives (reuseAccountId from options vs forceNew:true) selected by user preference. It also names the prerequisite action ('confirm with the user first').

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

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

Annotations only cover mutation safety (readOnlyHint=false, destructiveHint=false). The description adds substantial non-obvious behavior: no per-charge fee, KYC prerequisite, and — critically — the ~100x overcharge risk from zero-decimal currency handling. This is exactly the kind of high-stakes 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?

Front-loaded with the core action, then prerequisites, then the pricing pitfall, then the docs link. Dense but every clause earns its place; the em-dash parentheticals are justified by the overcharge risk they prevent.

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 no output schema and no descriptive annotations, the description still covers the critical pricing semantics, auth prerequisite, and a safe-usage warning. It omits what the tool returns (a checkout URL) and the payment-vs-subscription distinction, minor gaps for a link-generation 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 0%, so the description must compensate, and it does the heaviest lifting by fully explaining amountCents unit semantics and the zero-decimal exception (jpy, krw, vnd, clp) with a worked example. It leaves mode, lineItems structure, projectId, idempotencyKey, and the URLs undocumented, but the most error-prone parameter is covered well.

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 Stripe Checkout link'), and distinguishes the scope from the sibling topup_link by explaining it settles to the user's customers on their connected account. An agent can immediately tell what this produces without opening the schema.

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

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

Gives a concrete prerequisite ('Needs connect_stripe with KYC complete') and an explicit caution to confirm price/currency before invoking. No sibling alternative is named, but this tool has no direct alternative in the list, so guidance is strong though not a full when/when-not framing.

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 non-idempotent, but the description goes well beyond them: it enumerates precisely what is destroyed vs. kept (dataKept), states irreversibility, names a refusal precondition (live ad campaign), and mandates a user confirmation gate keyed to confirmName. That is far more than the structured hints convey.

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

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

Front-loaded with the destructive scope in the first clause, and each subsequent sentence carries distinct operational content (kept resources, ordering, refusal condition, confirmation rule, docs link). It is dense and somewhat run-on, but no sentence is filler.

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

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

For a two-parameter destructive mutation with no output schema, the description covers everything an agent needs: destruction scope, preservation semantics, required pre-steps and their tool names, refusal condition, and the confirmation protocol before 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 50% — confirmName is documented in the schema, projectId is not. The description compensates by explaining the confirmation contract ('confirmName = that name') and that it must be the exact, user-confirmed project name, which adds meaning beyond the schema's own text.

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 ('Delete a project') and immediately scopes it ('for good — irreversible'), plus enumerates exactly which resources go with it (servers, volumes, hosting, email domain). This clearly separates it from adjacent siblings like lavela.destroy_compute, lavela.destroy_resource, or lavela.list_resources, which are named 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?

Gives when-to-use and when-not: refused while an ad campaign is live, and managed databases/caches/storage are KEPT unless deleted first via lavela.list_resources → lavela.destroy_resource. It also prescribes the interaction protocol (show the exact project name and what gets deleted, call only after the user confirms) and points to how to unlock the advanced tool.

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

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

Annotations only cover readOnlyHint=false and destructiveHint=false; the description goes well beyond, disclosing the 30-minute expiry, one-link-per-service constraint, the CONSENT_REQUIRED first-call flow, and that the deployed server is billed to the lavela wallet. These are exactly the behavioral traits an agent needs before invoking.

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

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

The description is dense yet front-loaded, opening with what the link is before moving to handoff, polling, consent, and billing. Every clause carries information, though the packing of five distinct facts into a few sentences is slightly heavy.

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

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

For a mutating link-generation tool with annotations and no output schema, the description covers everything an agent needs: the deliverable, expiry, handoff instruction, polling next step, consent loop, and payment source. Return-value detail is unnecessary because no output schema exists and the verbatim `url` is called out.

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 only 50%: `service` is documented in the schema (default 'web'), but `projectId` has no description anywhere. The description adds meaning by noting 'One link per service', clarifying the service parameter's role, but does not explain projectId, so it only partially compensates for the coverage gap.

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

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

The description states a specific deliverable (a one-time browser link) and its precise scope (code that isn't on GitHub yet), with a concrete mechanic (connect GitHub and pick a repo, or drag in the folder). An agent can distinguish this from siblings like provision_compute_from_repo or connect_github 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?

It gives clear usage context ('code that isn't on GitHub yet') and the follow-up workflow (hand the url over verbatim, then poll lavela.compute_build_status {projectId}). However, it never names an explicit alternative for already-GitHub-hosted code, so the when-not-to-use case is only implied.

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

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

With destructiveHint already set, the description goes well beyond the annotation by disclosing exactly what is destroyed (the server's own disk), what persists (attached volume, still billed, daily snapshots, managed databases), and that billing stops. This is high-value consequence detail for a destructive call.

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 destructive verb and its immediate effect, then the persistence caveats, then the confirmation requirement and a docs link. Every sentence earns its place, though the clause chain about volumes/snapshots/databases is somewhat dense.

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

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

For a single-parameter destructive tool with no output schema, the description covers the critical unknowns: permanence, what survives, billing impact, and a user-confirmation requirement. Nothing essential to safe invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents machineId. The description adds meaning beyond the schema by telling the agent where to obtain it (lavela.project_overview) and by tying it to the confirmation step.

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 ('Permanently remove a server') and immediately scopes it with the machineId source. An agent can distinguish this from siblings like resume_compute, redeploy, or delete_project without opening any schema.

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

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

Gives clear context: use it to stop a server from running and being charged, and confirm the exact server with the user first. It doesn't explicitly name alternatives for adjacent operations (deleting volumes, snapshots, or databases), so routing is implied rather than enumerated.

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

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

Annotations already declare readOnlyHint=true, so the description's 'Free, read-only' is partly redundant, but it goes further by describing the diagnostic output shape (per-record expected vs found, HTTPS state, actionable fix list) that no output schema supplies. It also clarifies the operator intent ('what to relay'), which helps the agent present results.

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

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

Front-loaded with the core question ('Why a project's custom domain doesn't work yet'), followed by output contents, the usage rule, and a docs link. Every clause earns its place; the trailing URL is the only slightly expendable element.

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 no output schema, the description correctly takes on the burden of explaining what the tool returns, and it does so concretely. The remaining gap is the undocumented projectId, which is a minor omission for a single-parameter read-only diagnostic.

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

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

The single projectId parameter has zero schema description coverage, so the schema does not explain it. The description only implies the subject ('a project's custom domain'), leaving the agent to infer that projectId selects that project. Adequate but not compensating for the coverage gap.

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

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

States a specific verb (diagnose) and resource (a project's custom domain) and enumerates exactly what it reports: expected vs found DNS records, HTTPS issuance status, and a plain-language fix list. This is clearly distinguishable from the sibling lavela.provision_domain, which creates rather than diagnoses.

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

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

Explicitly names the trigger condition and ordering: 'Use it after lavela.provision_domain.' That routes the agent to the correct lifecycle stage. It lacks any when-not-to-use or alternative-branch guidance, which keeps it 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 only supply readOnlyHint=true; the description carries the real behavioral load — no value passes through the agent or chat, public entries land as build settings while the rest become write-only secrets, the command shows names only and requires the user to click Allow in their browser. That is substantial context the annotations do not convey, and it is consistent with a tool whose own call only produces a link/command.

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 the no-values-in-chat rule are front-loaded, and the follow-up clauses about command/url/next_step each carry actionable instruction. It is dense with semicolons and runs slightly long, but no sentence is filler.

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

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

With no output schema, the description correctly documents the three possible return shapes (command, url, next_step) and the browser-approval flow, which is the main thing an agent needs. It is incomplete on the input side — neither parameter's meaning nor any auth prerequisite is stated — which is the one real hole for a secret-handling tool.

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

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

Schema description coverage is 0% for two input parameters, so the description must compensate and it does not: `projectId` and especially `service` (which has a pattern and 63-char limit) are never explained. The identifiers `command`, `url`, and `next_step` that it discusses are return values, not the declared inputs.

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

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

The description names a specific action and resource — delivering the USER's .env into the app — and explains the split of public entries into build settings versus write-only secrets. That mechanism cleanly separates it from siblings like set_build_vars and set_compute_secret, which an agent can see 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?

It gives conditional handling for the result (run `command` in the user's project folder, else hand over `url` verbatim, else follow `next_step`) and a hard rule: never read a .env's values or ask for one in chat. It stops short of naming the alternative tools (set_build_vars / set_compute_secret) or stating prerequisites, so routing between siblings is left partly 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?

readOnlyHint=true already covers the safety profile, and "read-only" largely repeats it. The added value is the "Free" cost note and the two invocation modes, but it says nothing about freshness, retention, or rate limits. Adequate addition over annotations, not rich.

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

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

Two tightly packed sentences with zero waste: purpose and use cases first, invocation modes second. Nothing is filler.

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

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

With no output schema, the description usefully summarizes the log line shape and both calling paths, which is enough to invoke it. It omits the range/limit behavior and any fetch window, a minor gap for a read-only diagnostic 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 only 50% (limit and projectId undocumented), yet the description supplies the key fact the schema omits: that projectId + service (default "web") and machineId are alternatives ("or"). This clarifies mutual exclusivity and the service default. The limit parameter remains unexplained.

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

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

States a specific verb+resource (log lines of a server and its builds) and even names the returned fields (time, level, message). It is clearly distinguishable from siblings like get_errors, check_health, and compute_build_status.

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

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

Gives concrete triggering scenarios — debugging a failed build, a crash, or a wrong port. It lacks explicit when-not guidance or routing to an alternative diagnostic sibling such as get_errors, but the use context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and the description echoes 'free, read-only', so safety is covered. The real added value is the warning that hosting 'active' isn't proof the app works and that a false `verified` with `verifyWarning` means the page looks broken — post-call interpretation guidance the annotations cannot supply. It stops short of describing polling cadence or state transitions.

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 module list, then the polling trigger, then the caveat, then a docs link. Dense but every clause carries information; slightly overstuffed with an ellipsis list and a trailing URL.

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?

No output schema exists, and the description partially compensates by naming the modules returned, the 'next step' field, and the `verified`/`verifyWarning` semantics. An agent can call and interpret this confidently, though the exact response shape per module remains unspecified.

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 only 50%: `id` has a description ('Same as projectId') but `projectId` has none, and the tool description says nothing about either parameter. With low coverage the description should compensate, and it does not — an agent must infer that the two UUIDs are interchangeable aliases.

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 resource (a project's status) and enumerates the module dimensions it reports (hosting, compute, domain, email, stripe) plus the next-step output. This is clearly distinguishable from siblings like account_status, project_overview, and check_health.

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

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

Explicitly says when to call it — poll after provision_hosting, redeploy, provision_domain, provision_email, or connect_stripe — which is exactly the lifecycle context an agent needs. No exclusions are given, but the trigger set is precise.

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=false and idempotent=false, and the description adds the consequences the annotation can't: a retry creates a second project, and despite creating a project nothing is deployed or charged. The deploy/next_step/blockedBy gating is genuinely new behavioral context absent from 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?

Purpose is front-loaded in the first clause, followed by behavioral caveats, the non-idempotency warning, and a docs link. Dense but each clause carries information; slightly heavy use of arrows/backticks adds friction without padding the length.

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

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

No output schema exists, and the description compensates by naming the response's guidance fields (deploy, next_step, deploy.blockedBy) so the agent knows what to do with the result. The main gap is the unaddressed business sub-object, which an agent cannot infer from the bare schema.

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

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

Schema description coverage is 0%, so the description must compensate, and it only covers name and the GitHub repo (source.githubUrl) in prose. The entire business object (name, country, industry, description — including constraints like the 2-char country) is never mentioned, leaving a third of the parameter surface undocumented in both places.

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

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

States a concrete verb+resource ("Create a project") plus its two key inputs (name, GitHub repo) and immediately bounds the action: "nothing is deployed or charged." That negation separates it from the provisioning siblings (provision_compute_from_repo, provision_hosting) without the agent needing to open either schema.

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

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

Gives real sequencing guidance: check lavela.list_projects before retrying because the call is non-idempotent, and follow the returned next_step, fixing deploy.blockedBy first. It stops short of naming alternate siblings (e.g. when to prefer provision_compute_from_repo instead), so it is clear context rather than 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?

Annotation readOnlyHint=true already establishes the safe-read profile, so 'read-only' is partly redundant. The description does add cost context ('Free') and discloses the includeArchived behavior, but says nothing about result shape, ordering, or pagination — modest value over the annotation.

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

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

Three short clauses, front-loaded with the core purpose and free of filler. Every sentence carries information, though the 'Then ...' clause is slightly awkward as a placeholder next-step rather than a usage condition.

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 trivial one-optional-param list tool with no output schema, the description covers purpose, the parameter behavior, cost, and safety. It does not describe the returned project representation, which is a minor gap for a discovery tool an agent may need to interpret.

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

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

Schema description coverage is 0%, so the description must carry the lone parameter, and it does: 'archived ones too with includeArchived:true' precisely explains what the boolean does and its default-off behavior. This compensates well for the undocumented 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 clear verb ('List') and resource ('the user's projects') and clarifies scope via the parenthetical about archived projects. It does not directly contrast itself with siblings, though the sequencing hint toward lavela.project_overview implies the read-then-drill-down relationship.

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?

'Then lavela.project_overview for one of them' hints at a workflow and names the natural follow-up tool, giving implied usage. However, there is no explicit when-to-use/when-not guidance, and no conditions distinguishing when to reach for this versus other listing/discovery siblings.

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

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

Annotations already declare readOnlyHint=true, and 'Free, read-only' largely restates that. The description does add some non-schema behavior: that the returned ids feed lavela.destroy_resource, that destroy_resource is an advanced tool requiring a reconnect, and the meaning of the usedBy:'hosted_app' marker. That is useful but leans more on ecosystem context than on this tool's own operational traits (pagination, auth, result shape).

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?

It is information-dense and opens with what is listed, but the sentence is heavily parenthetical and backticked, packing markers, a sibling-tool aside, and a reconnect URL into one tangled clause. It is neither bloated nor cleanly front-loaded.

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

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

With an output schema present, return values need no explanation, and for a read-only one-parameter list tool the description covers resource types, the destroy_resource id linkage, and use cases. It is essentially complete; only the projectId format is left unstated.

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

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

Schema description coverage is 0%, so the description must carry the single projectId parameter, which it only implies via 'A project's ...'. It never states the expected uuid format or that projectId is required, leaving meaning to inference from the schema.

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

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

The description enumerates exactly what is listed (managed databases, caches, storage, error tracking under type:'managed', and volumes under type:'volume'), which is more informative than the terse title. It does not name sibling list tools like list_projects, but the enumerated resource types let an agent distinguish it well enough.

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 concrete when-to-use cues: 'Call it before re-creating a database after a timeout, and to clean up.' That is clear context for the invocation, though it states no exclusions or rival tools to prefer instead.

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

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

Annotations only supply readOnlyHint, so the description carries the real burden and delivers unusual depth: asleep_awake semantics (awakeShare null = pace unknown, estMonthlyUsd = cap), that a removed server is not_running even if its build said 'ok', and that `live` null means unchecked. Minor duplication of 'read-only' from the annotation, but net value is high.

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 information-dense; almost every clause conveys distinct return-data meaning. It is notation-heavy with backticked field names, which makes it read like a data dictionary rather than prose, but little is wasted.

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

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

With no output schema, the description must explain the return payload, and it does so comprehensively for a read tool: it lists every domain covered and disambiguates the ambiguous states (awakeShare, live, not_running). Combined with the readOnlyHint annotation, 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?

One required parameter at 0% schema description coverage. The phrase 'one project in one call' implies projectId selects the target, but the description adds no format, source, or constraint details beyond that inference, leaving the parameter only weakly documented.

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 ('everything to operate one project in one call') and then enumerates the exact contents returned (URLs, server state, prices, machineIds, last build, hosting, domain, email, payments, databases, volumes, balance). This differentiates it from siblings like list_projects and get_status by scope and depth.

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

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

Gives explicit routing ('Start here for an existing project') and names lavela.check_health as the tool that actually checks health when `live` is null. It does not state when NOT to use it versus list_projects or account_status, so it falls just short of full when/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 only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond them, disclosing that re-calling replaces the existing server, the async build/poll lifecycle and failure handling, wallet-based billing with a balance/pricing lookup, and the private/always-on DB-cache port behavior. This is unusually rich behavioral context for a mutation tool.

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

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

Front-loaded with the core capability and then the routing rule, and nearly every clause carries actionable information (polling, billing, port behavior). It is very dense — all-caps emphasis, stacked parentheticals, and doc links make it harder to scan than it needs to be, but there is little true 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 10-parameter mutation with nested objects, no output schema, and only two required fields, the description covers the build lifecycle, the async result path, cost/consent requirements, and per-parameter defaults and redeploy carry-over. An agent has everything needed to invoke it correctly and follow up on the build.

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 90%, so the schema carries most parameter meaning. The description still adds operational semantics not in the schema — the defaults packaged as 'repo root, default branch, 8080, no env' and the rule that a redeploy keeps size, mounts, and alwaysOn unless overridden — which meaningfully changes how an agent should set or omit arguments.

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 (build a GitHub repo and run it as a server with a public URL) plus the differentiator (any runtime, no Dockerfile needed). It explicitly names a sibling, lavela.compute_rebuild, as the tool for the redeploy case, so an agent can separate the two 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 routing ('REDEPLOYING a service it already built? Use lavela.compute_rebuild'), the async follow-up loop ('poll lavela.compute_build_status {buildId} until ok/failed'), and a hard precondition to confirm payment with the user before calling. Both alternatives and a prohibited-inference condition 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?

Adds substantial behavior beyond the annotations: no backups / short provider history with "dump your own", funded-account requirement, no usage charge today, idempotent behavior ("same name again returns that database"), and what wireToService does versus returning the connection string. These are real operational caveats an agent must know.

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

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

Front-loaded with the purpose and dense with useful detail, but the heavy parentheticals and em-dash clauses make it read as a packed run-on rather than cleanly structured sentences.

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

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

For a mutation tool with no output schema, it covers the important bases: prerequisites, idempotency, side effects of wireToService, durability caveats, and a docs link. Nothing critical to calling 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 67%; the description adds meaning for wireToService by explaining that DATABASE_URL is injected into an existing server, else the raw string is returned. The name default is already in the schema and projectId is left unexplained, so it does not fully compensate for the coverage gap.

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

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

States a specific verb+resource ("Create a managed Postgres under lavela") and scopes it as a persistent managed database, which is inherently distinct from the compute/domain/email provisioning siblings. An agent can immediately tell this is the database-provisioning tool.

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

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

Gives clear prerequisites and context: "Needs a funded account", "Confirm with the user", and the no-price warning. It does not name an alternative tool or a when-not-to-use condition, so it stops short of explicit alternative 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?

With annotations only declaring readOnly=false and destructive=false, the description adds substantial behavioral context: the verification difference between 'hosting' (auto-verified + HTTPS) and 'compute' (does not self-verify, must poll get_status), plus cost ('Free'). This goes well beyond what annotations provide.

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

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

Dense but well front-loaded: purpose first, then the target-mode distinction, prerequisites, fallback tool, and docs link. Every clause carries actionable information with no filler.

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

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

No output schema exists, yet the description explains what is returned (DNS records) and the follow-up behavior (poll get_status for compute). For a mutation tool with no annotations detail and no output schema, the description covers everything an agent needs to invoke it correctly.

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

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

Schema coverage is 0%, so the description must carry the load; it meaningfully explains the 'target' enum values and their defaults and ties the 'service' param to the compute target. However projectId and domain are not described at all, leaving a partial gap for a 4-parameter tool.

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

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

States a specific verb+resource (connect a domain) and immediately scopes it with the key qualifier that the user must already own it. It also clarifies what the tool returns (DNS records to add at the registrar), making it clearly distinct from siblings like provision_hosting and diagnose_domain.

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

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

Explicitly gives prerequisites ('The app must be deployed first') and routes troubleshooting to the alternative ('Not working yet? lavela.diagnose_domain'). It also explains the when-to-choose logic between the two target modes, so 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 only declare readOnly=false and destructive=false; the description adds materially more: account-funding requirement, refusal of platform-owned domains, an asynchronous two-call verification pattern, and the name of an output field (ownershipVerification). This is rich behavioral context beyond the structured hints.

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

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

Three dense sentences, front-loaded with the core action and benefit, then prerequisites and the fallback flow. Every clause earns its place; the docs link is deferred to the end.

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

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

For a two-parameter mutation with no output schema and only minimal annotations, the description covers prerequisites, refusal conditions, async semantics, the manual verification fallback, and even a referenced return field. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 0%, so the description must carry the load. It clarifies that 'domain' means a domain the user owns and that it must be this project's live connected domain, which adds real meaning, but projectId is never explained and neither parameter's format or relationship is elaborated.

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

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

States a specific verb and resource ('Set up authenticated sending (DKIM/SPF/DMARC) on a domain') with the goal ('email lands in inboxes'). Clearly distinct from sibling provision_domain, which would be about registering the domain rather than configuring its sending authentication.

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

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

Gives explicit conditional flows: automatic ownership proof for a live connected domain, otherwise publish the ownershipVerification TXT record and call again. Also states prerequisites (funded account), refusals (lavela-owned domains), and the follow-up action (poll lavela.get_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 readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds substantial context beyond that: the operation is async, must be polled via lavela.get_status until active ('verified') or failed, and requires a funded account. Return format is not described, but the async completion protocol largely covers 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?

Front-loaded with the core purpose, then the routing rule, then the async workflow, then the docs link. Sentences are dense but each carries actionable information; the only minor cost is heavy parenthetical nesting that slightly slows parsing.

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?

No output schema exists, yet the description covers the essentials for a deployment tool: prerequisite account state, the sibling that handles the other case, and the exact async completion signal to watch. Remaining gaps (framework param semantics, return shape) are minor given the async protocol is spelled out.

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 67%, with rich schema-level docs for env, branch, subdir, and githubUrl (encrypted storage, redeploy persistence, monorepo subtree). The description itself adds almost no per-parameter meaning ('from GitHub' only gestures at githubUrl), so the schema carries the load and the uncovered framework/projectId params remain undocumented in both places.

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

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

States a specific verb and resource ('Deploy a WEB FRONTEND ... from GitHub to a live URL') and enumerates the supported frameworks, so the agent knows exactly what gets deployed. It explicitly distinguishes itself from lavela.provision_compute_from_repo by naming the condition that routes to the 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?

Names the alternative tool (lavela.provision_compute_from_repo) and the exact conditions selecting it ('an app with its own server, or any app on the free welcome credit'), and points to launch_saas's next_step for the decision. This is explicit when/when-not guidance, not 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 only say readOnly=false and destructive=false, so the description carries the interesting behavior: redeploy reuses the last successful deploy's repo/folder/branch and the project-stored env, a CONFLICT signals an in-flight deploy, and the compute alternative 'replaces the running server' when given settings. That is real context beyond the annotations. It stops short of saying what the call returns (a deploy id?) or how long a rebuild typically takes, which is the kind of detail needed to poll sensibly.

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

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

Front-loaded with the core action and the minimal invocation, then the polling/CONFLICT rule, then the compute exclusions – a sensible priority order with no filler. The middle clauses are dense and run long ('with that id redeploys it (same branch — pushed code included — folder, size, port, env, mounts)'), which costs a little readability.

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

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

Given no output schema, the description still tells the agent the call is asynchronous (poll get_status) and enumerates the sibling routing decisions an agent is most likely to confuse. The remaining gap is the return value of redeploy itself and how to observe completion or failure beyond get_status, which a fully complete definition for an async mutation would include.

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 80% and documents the env/branch/subdir defaulting behavior, and the description reinforces it ('Call it with just projectId', the same repo/folder/branch are reused). The branch rule for names containing '/' is schema-provided rather than repeated, so the description adds alignment with the no-arg invocation model rather than new per-parameter syntax.

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 ('Redeploy a web-hosting project from its latest repo state') and immediately scopes it by noting the rebuild reuses the last successful deploy's repo, folder, branch and stored env. This lets an agent distinguish it from the compute siblings named later in the description 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 routing guidance: 'Call it with just projectId', poll lavela.get_status (CONFLICT means one is already running), and an explicit exclusion 'NOT for a server on compute' that points to lavela.compute_build_status / lavela.compute_rebuild, plus when provision_compute_from_repo applies (first deploy or confirmed settings). Both when-to-use and when-not-to-use are covered with named alternatives.

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

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

Annotations only give readOnly=false, idempotent=true, destructive=false. The description adds preconditions (balance must cover the pause, human review blocks it), the automatic top-up behavior, the cost profile ('Free'), and an explicit non-effect (does not start servers). Those are exactly the behavioral traits 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?

Three dense sentences with the primary action front-loaded and no filler. The middle sentence is slightly compressed into an awkward fragment ('It doesn't start servers: then lavela.compute_lifecycle action start'), but nothing is wasted.

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

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

For a zero-parameter mutation with an output schema and idempotent/non-destructive annotations, the description covers the remaining gaps: preconditions, refusal cases, default automatic behavior, alternatives, and cost. 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?

The tool takes no parameters, so the schema fully covers the surface and there is nothing for the description to add. Baseline for zero parameters applies, though the description does usefully imply that project/instance identity is not passed here (IDs come from lavela.project_overview).

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 ('lift a compute pause from the wallet running out') and immediately scopes it against the close sibling, clarifying it is the billing-pause resume rather than a server start. An agent can distinguish it from lavela.compute_lifecycle and lavela.destroy_compute 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 names the alternative for a related-but-different need (lavela.compute_lifecycle action 'start'), tells where IDs come from (lavela.project_overview), and states when this call is refused (balance still short, or a person must review the pause). It also notes the common case where the action is automatic, which prevents unnecessary calls.

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

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

Annotations only declare readOnly=false, idempotent=true, destructive=false. The description adds substantial behavior beyond that: nothing restarts or is billed on store, secret-looking names or values are refused, and the change only takes effect on the NEXT build. It also warns that the follow-up rebuild replaces the running server, which is critical operational context.

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

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

Front-loaded with the core definition before branching into routing and sequencing rules, and every clause carries operational weight. It is dense with parenthetical asides, which slightly hurts scannability, but nothing is padded.

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

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

For a mutation tool with no output schema, it covers the safety profile (refusals), the side-effect profile (no restart/billing), the read path (call with neither to retrieve), and the required follow-up step. An agent has everything needed to invoke it correctly and responsibly.

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 75%, and the description closes the remaining gap by explaining the control-flow of the parameters ('vars sets, unset removes; with neither, the current set comes back'), including the get/read behavior that the schema does not express. It also restates the public-prefix constraint that governs valid var names, though projectId and service add little 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 and resource ('Store PUBLIC build settings') and immediately defines what 'PUBLIC' means in operational terms (values a bundler bakes into shipped JavaScript). It explicitly positions itself against siblings by naming set_compute_secret and env_link as the destinations for non-public data, so an agent can route correctly without opening other 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 routing rules: secrets go to lavela.set_compute_secret, a whole .env goes to lavela.env_link, and a rebuild must follow via lavela.compute_rebuild (with the caveat to confirm first because it replaces the running server). This is when-to-use, when-not-to-use, and downstream sequencing all in one.

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

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

Goes well beyond the readOnlyHint=false / destructiveHint=false annotations: it discloses encryption at rest, boot-time injection, that values are never returned, that the default behavior restarts the running server, and that the operation is free. These are exactly the side effects an agent needs before invoking a mutation.

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?

Dense but front-loaded: what it stores, why it is safe, the alternative it replaces, then the side-effect/cost caveat. No sentence is filler and the apply:false nuance is handled in a short parenthetical.

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 mutation tool with no output schema and reasonable annotation coverage, it supplies the safety profile, default side effect, and cost. It omits authorization/permission requirements and whether unset also triggers a restart, which are the remaining gaps an agent might need.

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

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

Schema coverage is already 80% and documents apply, unset, and service. The description reinforces the apply semantics ('next deploy uses them') but says nothing about unset (secret removal) or service selection, so it adds only marginal meaning over the structured fields.

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

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

States a specific verb and resource (store write-only secrets for a server) and immediately characterizes the payload (API keys, DATABASE_URL). The phrase 'use this, not env, for credentials' actively separates it from the env-related siblings (env_link, set_build_vars). An agent can identify the tool 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?

Gives a clear when-to-use rule ('for credentials') plus an explicit not-condition ('not env'), and explains the apply:false branch as the store-only path. It stops short of naming the actual sibling tool that handles non-secret env vars, so the routing is directional rather than exhaustive.

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