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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by spelling out the concrete consequence — calling again silently creates a duplicate with the same name — which is exactly the failure mode an agent would otherwise hit. It omits cost implications and whether the addon can be removed later.

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

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

Two sentences, front-loaded with the trigger condition, and every clause earns its place — including the duplicate-creation warning, which is the highest-value line in the definition.

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

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

A destructive, non-idempotent provisioning call with no output schema and 50% param coverage warrants more: how the agent retrieves connection details afterward (secrets_refs? service_show?), what happens on partial failure, and whether duplicates can be cleaned up are all unaddressed. The trigger and duplicate warning are solid, but the post-creation story 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 50%: name and region are documented in-schema (region even includes a 'call region_list first, do not guess' directive), while project is undocumented. The description only restates the type enum values and adds nothing about project scoping or name reuse rules — one sentence on what 'project' accepts would have compensated for the 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: 'provision a managed database or storage addon (Postgres, Redis, or S3) in a Lizard project.' That clearly separates it from nearby siblings like volume_create and service_create, though it never names those alternatives 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?

'Use this when the user wants to provision...' gives a clear trigger condition, and the second sentence rules out a tempting misuse ('it does not update an existing one'). No named alternative for updating or looking up an existing addon, so it stops short of a full when/when-not map.

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 a safe read (readOnlyHint/idempotentHint true, destructiveHint false, closed-world), and the description adds substantial context beyond them: mutations (starting Pro, paying, cancelling) must be done by the user in the browser at billingUrl, and the agent should hand over that link. It also explains the deprecated 'payg' value and the $19 pricing model, which no structured field conveys.

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 trigger condition is front-loaded, followed by return values, pricing, and the action handoff — a sensible order with no filler sentences. It is somewhat dense, particularly the long enumeration of returned fields inside one sentence, but every clause carries information an agent needs given there is no output schema.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly: plan enum values, Pro status values, trial days/credits, monthly usage and overage, next charge, pending cancel, unpaid invoice link, and billingUrl. Combined with the annotation-covered safety profile and the explained workspaceId behavior, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100% and the single optional workspaceId is already documented in the schema. The description's 'With workspaceId, reads that workspace owner's plan' restates that meaning without adding new syntax, defaults, or edge cases beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource (returns the account's plan and billing status) and enumerates the fields returned, so an agent knows exactly what it gets. It does not, however, distinguish this from the sibling billing_summary, which an agent could easily confuse with this 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?

Clear trigger conditions are given: use it when a tool fails with PAYMENT_REQUIRED, or when the user asks about plan, trial or bill. What's missing is the alternative — the sibling billing_summary is never mentioned, so there is no guidance on which of the two to choose.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety behavior is fully covered by structured data. The description adds the useful detail that the result reflects live spend and current usage (not cached/invoiced totals), but says nothing about permissions, freshness, or data sources beyond that.

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

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

A single sentence that front-loads the usage trigger before the scope and payload description. No filler, though the trailing 'including current usage and live spend' is slightly loose wording.

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

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

For a simple read-only, single-parameter tool with rich annotations, the description covers the essentials of what the call returns. It still omits any mention of the sibling 'billing_status' distinction and any statement about what the summary actually includes (line items, period, currency), which would matter when choosing between the two.

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 explain the single workspaceId parameter. It only alludes to it via 'for a Lizard workspace', never stating that workspaceId identifies which workspace to bill or what format the ID takes, so the parameter's meaning is inferred rather than 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?

The description names a specific verb+resource combination: a cost/billing summary for a workspace, plus what it contains (current usage and live spend). It is clearly distinct from most siblings, but it never distinguishes itself from the adjacent 'billing_status' tool, so an agent cannot disambiguate the two from the text alone.

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

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

The opening clause ('Use this when the user wants a cost/billing summary') gives a usable trigger condition. However, there are no exclusions or prerequisites, and the obvious alternative 'billing_status' is never mentioned, leaving the agent to guess which billing tool to pick.

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

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

Annotations already declare readOnly, idempotent, non-destructive and scoped (openWorldHint=false), so the safety profile is covered. The description usefully adds the sort order and the fact that runs come from .lizard/workflows, but says nothing about result limits, defaults, or pagination behavior for a 'recent' list.

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

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

A single front-loaded sentence that packs resource, location, ordering, and filters without filler. The clause about GitHub Actions syntax is slightly tangential but clarifies what 'workflows' means.

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

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

For a read-only list tool with full annotation coverage and no output schema, the description covers what is being listed and how it is ordered. It omits the size/shape of the result set ('recent' is unbounded) and default behavior when no filters are passed, which an agent needs to reason about the response.

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

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

With schema description coverage at 50%, the description does add meaning for the undocumented 'pr' parameter by identifying it as a pull request number, and confirms branch/status as filters. It still gives no format or matching semantics (exact vs. prefix branch match, how many results returned), so it only partially compensates.

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

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

States a specific verb and resource ('List recent CI runs') plus scope (a Lizard Git repository, workflows under .lizard/workflows, GitHub Actions syntax) and ordering (newest first). The singular/plural split from the sibling ci_run_show is inferable but not explicitly called out.

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

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

Filter dimensions (branch, pull request number, status) imply the discovery use case, giving some context for when to call it. However, there is no explicit guidance on when to prefer it over ci_run_show for a single run's details, nor on prerequisites like repo access.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so behavior beyond that is largely covered. The description still adds real value by disclosing that logs are truncated to 64 KiB per job and where in the log failures tend to appear – a non-obvious cost/quality trait.

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 dense sentences with the primary purpose front-loaded and the optional-parameter caveat immediately after. Nothing is padded or repeated from the title.

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

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

For a simple 3-parameter read tool with full annotation coverage, the description covers what is needed to invoke it correctly. Without an output schema, it never sketches the returned run/job/step structure, which is the only remaining ambiguity.

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 33%, so the description must compensate and it does for `logs` – explaining exactly what true adds and its truncation limit, which the schema does not. `repo` is documented in the schema (owner/name, pointing at repo_list); `number` is left implicit but is self-evident as a CI run identifier bounded to >=1.

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

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

States a specific verb and resource (read one CI run of a Lizard Git repository) plus the payload scope (its jobs and steps). That implicitly separates it from the sibling ci_run_list, which returns many runs.

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?

Clearly establishes the context (fetch a single run, presumably when you already have a run number) and gives a concrete usage rule for the logs flag: set true to pull job logs, which are truncated to the last 64 KiB where failures usually are. It does not name ci_run_list as the way to discover run numbers, so no 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the concrete consequence: the body 'is passed through verbatim and can overwrite or remove existing fields'. That tells the agent what actually gets destroyed rather than just that the call is destructive. It stops short of covering failure/validation behavior or result shape, so not a full 5.

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

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

Two sentences, no filler. The usage trigger and scope come first, the destructive warning and alternative follow — front-loaded in the order an agent needs to make a decision.

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

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

For a destructive tool taking an unconstrained nested object with no output schema, the definition covers when-to-use and the overwrite risk, but leaves the agent with no notion of the expected body shape or what the call returns. Adequate for routing, thinner for actually constructing a correct invocation.

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

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

Schema coverage is only 50%: the 'config' object is documented as an arbitrary verbatim body validated server-side, while 'project' has no description at all. The description reinforces the config semantics with the overwrite/removal warning but says nothing about what the config body should contain or what 'project' expects, 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 names a specific verb and resource ('apply a bulk, config-as-code style configuration to a Lizard project in one request') and explicitly scopes it to multi-resource edits ('multiple services/addons/secrets at once'). It distinguishes itself cleanly from the single-field siblings by naming 'service.*/secrets.* tools', so an agent can route correctly without opening a schema.

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

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

It gives an explicit trigger ('when the user wants to apply a bulk... configuration') and an explicit exclusion with the alternative named ('prefer the narrower service.*/secrets.* tools for single-field changes'). Both the when and the when-not are stated rather than inferred.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely new information by disclosing what is returned (deploy/build history plus current replica status), which matters since there is no output schema. It does not say how far back 'recent' goes or whether results are limited/paginated.

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

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

A single front-loaded sentence with the usage trigger first and the payload second. No filler or repetition of the title.

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

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

For a simple two-parameter read tool with full annotation coverage, it conveys the job and the return content adequately. The missing piece is parameter meaning (what 'project'/'service' identifiers look like) and any notion of result window or size.

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 both parameters (project, service) are required but never mentioned. The phrase 'for a Lizard service' vaguely hints at the service param, but project is entirely undocumented, so the description does not compensate for the schema 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 ('see') and two concrete resources: deploy/build history and replica status for a Lizard service. It is clearly a read operation, distinguishing it implicitly from deploy_redeploy/deploy_restart, though it never names those siblings.

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

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

The opening 'Use this when the user wants to see...' gives an explicit trigger condition. There are no when-not conditions or named alternatives, but the positive guidance is clear enough for an agent to route correctly.

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

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

Adds genuinely non-obvious behavior beyond the annotations: the call returns immediately after the build is triggered (async), and every call starts another build even if repeated immediately – reinforcing the idempotentHint=false and destructiveHint=true declarations rather than contradicting them. It stops short of saying what happens to the currently running instance during the rebuild, which would complete the destructive picture.

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

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

Three tight sentences: purpose, return/async semantics, and follow-up tool. Front-loaded with the when-to-use clause and no filler.

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

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

The async behavior and progress-check path are covered, but with no output schema the agent is not told what the immediate return contains (build ID? status object?) or how much time to wait before polling. Combined with entirely undocumented parameters, the definition is adequate but leaves meaningful gaps for a mutating deploy 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 required parameters, so the description carries the full burden – but it never mentions 'project' or 'service' at all, and gives no hint whether these are names, slugs, or IDs. The parameter names are somewhat self-descriptive, which prevents a 1, but the gap is real.

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?

Uses a specific verb+resource ('trigger a new deployment of an existing Lizard service') and clarifies the scope as 'rebuild and redeploy current source', which meaningfully separates it from a plain restart. It does not explicitly contrast with the sibling deploy_restart, which is the most confusable alternative.

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 condition ('when the user wants to trigger a new deployment of an existing Lizard service') and routes the agent to deploy_events for progress tracking. It omits any explicit exclusion or comparison against deploy_restart, so the main ambiguity an agent faces is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds useful behavior beyond that: it says the call returns immediately and that repeated calls restart the service again, clarifying the non-idempotent runtime effect.

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

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

The description is three tight sentences: usage condition first, then immediate-return behavior, then repeated-call semantics. Every sentence adds distinct 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?

Annotations cover the destructive and non-idempotent safety profile, and the description covers timing and repeat behavior. However, for a destructive mutation tool it omits parameter explanations, prerequisites, and what 'destructive' means in practice, such as downtime or dropped in-flight requests.

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 required parameters, project and service. The description provides no meaning for either parameter, so it does not compensate for the missing schema documentation.

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

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

The description states a specific verb and resource: restart a running Lizard service. It also distinguishes the action from rebuild-based deploys by saying 'without rebuilding it', which helps separate it from deploy_redeploy.

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

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

It gives a clear condition for use: when the user wants to restart a running service without rebuilding. It does not explicitly name alternatives such as deploy_redeploy for rebuilds or service_resume for stopped services, so it stops 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?

Although annotations already flag destructiveHint=true and idempotentHint=false, the description adds real behavioral detail the annotations cannot convey: the refused-and-listed conflict case, force:true as the override, that DNS is auto-configured for Lizard-owned domains but returned as manual records otherwise, and that the call mints a fresh subdomain when repeated without hostname. It also tells the agent what the response contains, which matters because there is no output schema.

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

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

A single dense paragraph, but front-loaded with the fact that changes the decision (the domain already exists) before the when-to-call rules, the conflict behavior, and the follow-up step. No filler sentences; every clause carries decision-relevant information.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the safety-critical cases (refusal, force override, DNS side effects, verification follow-up) and even summarizes response contents. The remaining gap is `port`, which neither description nor schema explains, so an agent cannot tell when to supply it.

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

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

Schema coverage is only 40%, so the description carries extra burden. It meaningfully explains hostname (custom vs. generated) and force (replace conflicting records), but `port` is completely undocumented anywhere, and project/service are only implied by the required-parameter list. Partial compensation 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 and resource (attach a domain) and immediately scopes it against the automatic *.onlizard.com domain that every app already has. It distinguishes itself cleanly from siblings like domain_verify, domain_delete, and domain_dns_update by describing both the custom-hostname and the generate-subdomain modes.

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/when-not: only call when the user explicitly wants a custom domain, or when service_show shows no domain at all, and it tells the agent to read service_show's `domain` field first rather than guessing a hostname. It also names the downstream alternative (domain_verify) for the manual-DNS path and warns that repeat calls without hostname create yet another subdomain instead of returning the existing one.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's "This is destructive" largely restates structured data. It does add one piece of real context: confirmation must be explicit because there is no interactive prompt, reinforcing the confirm param. It says nothing about what happens to DNS records, whether the operation is reversible, or prerequisite verification.

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 short sentences, front-loaded with the triggering condition and followed by the safety note. No filler; the only slight redundancy is the destructiveness claim, which annotations already carry.

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

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

For a destructive 4-required-param tool with no output schema, the description covers intent and the confirmation gate but leaves the three identifier parameters undocumented and doesn't say what the result of a successful delete looks like. Adequate to call safely, incomplete to call precisely.

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 only 25% – just confirm is documented. The description does not explain project, service, or hostname at all, so an agent has no help on whether hostname must be an attached domain, whether project/service accept slugs or IDs, or format expectations. With low coverage the description needed to compensate and does not.

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

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

States a specific verb and resource: remove a custom domain from a Lizard service. This clearly separates it from domain_attach, domain_verify, and the domain_*_list siblings. It could be a touch sharper about scope (e.g. that the domain's DNS records go with it), but the core purpose is unmistakable.

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

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

"Use this when the user wants to remove a custom domain" gives an explicit triggering intent, which is more than most siblings offer. There is no when-not guidance or named alternative (e.g. detach vs delete), so it stops short of a 5.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds valuable context beyond annotations by listing the returned record fields (name, type, value, TTL, MX priority) and clarifying that '@' represents the domain itself. It does not mention pagination or error behavior, but for a simple read-only list tool the added return-field detail is useful.

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

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

The description is a single well-structured sentence that front-loads the tool's action and then lists the returned fields. Every clause earns its place with no wasted text.

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

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

For a simple read-only tool with full parameter schema coverage and rich annotations, the description is largely complete. It enumerates the returned record fields even though no output schema exists. Minor gaps include no mention of error cases (e.g., domain not owned) or whether results are limited.

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

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

Schema description coverage is 100%, and the domain parameter is documented as 'A domain from domain_owned_list, e.g. example.com'. The description adds only that the domain must be 'bought on Lizard' and that '@' denotes the domain in record names, which is marginal beyond the schema. Baseline 3 is appropriate when the schema already fully documents the single parameter.

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

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

The description states a specific verb and resource: 'Read the DNS records of a domain bought on Lizard.' It also enumerates the record fields returned, making the tool's purpose clear. It does not explicitly differentiate from the sibling domain_dns_update, but the read-only framing distinguishes it naturally.

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

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

Usage is implied by 'Read the DNS records' and by the domain parameter referencing domain_owned_list, but the description never states when to use this tool versus domain_dns_update or domain_verify. No explicit exclusions or alternatives are given.

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

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

The description adds substantial context beyond the annotations: set is a full replacement, remove deletes matching records, propagation usually takes minutes, and user approval should be obtained before remove. This meaningfully expands on destructiveHint=true and idempotentHint=false.

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

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

The description is front-loaded with purpose, then action semantics, type notes, alternative tool, auth, propagation, and approval guidance. Every sentence carries useful 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?

For a destructive DNS mutation with eight parameters, the description covers the essential invocation semantics, auth constraints, propagation expectations, and the key alternative tool. The remaining details, such as confirm and TTL, are already documented in the 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 coverage is high, but the description adds real meaning for the action enum by explaining set/add/remove behavior and clarifies record-matching semantics for remove. It also explains redirect type variants, though TTL and priority are left entirely to the schema.

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

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

The description opens with a specific verb and resource: 'Change one DNS record of a domain bought on Lizard.' It clearly distinguishes this from domain_attach by saying that pointing a name at a Lizard app should use domain_attach instead.

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

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

It explains the three actions explicitly: set replaces matching records, add keeps others, and remove deletes matching records. It also gives the key alternative for Lizard apps and states that a signed-in user is required, with API keys limited to reading.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: it requires a signed-in user or API key with no scopes, and it explains return fields including status and whether a domain points at an app.

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

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

The description is compact and front-loaded. It states the purpose first, then summarizes returned fields and auth requirements without wasting space.

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

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

For a simple read-only list tool with no parameters, rich annotations, and no output schema, the description is complete enough. It explains what is listed, what fields are returned, and the authentication needed.

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

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

The tool has zero parameters and an empty input schema, so there are no parameter semantics to clarify. The baseline for zero parameters is 4.

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

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

The description states a specific verb and resource: 'List the domains the user bought on Lizard.' It adds useful scope with returned fields, but it does not explicitly distinguish this from sibling tools like domain_dns_list or domain_attach.

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

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

The auth prerequisite is stated, but there is no explicit guidance on when to use this tool versus alternatives such as domain_dns_list, domain_verify, or domain_attach. Usage is implied by 'domains the user bought' rather than spelled out.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false for a tool whose name and description both sound like a passive check, and the description does nothing to explain that mismatch or what state could actually be altered. With annotations present the bar is lower, but this gap is exactly the kind of surprise (a 'verify' that is destructive) an agent needs disclosed, plus there is no mention of required auth or rate limits.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity is partly under-specification rather than discipline given the tool's complexity.

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

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

No output schema exists, so the description must explain what verification produces (a pass/fail result? per-record diagnostics?) and it does not. Combined with three fully undocumented parameters and destructive annotations that are never acknowledged, an agent lacks what it needs to call this confidently.

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 all three required parameters, so the description must compensate and it does not — it never mentions project, service, or hostname individually. At best the phrase 'custom domain attached to a service' hints that the parameters identify a project/service/hostname triple, which is marginal value.

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 (verify) and resource (DNS configuration for a custom domain attached to a Lizard service), which is enough to tell it apart from the list/update siblings like domain_dns_list and domain_dns_update. It stops short of saying what 'verify' actually does (check records? trigger re-validation?), so it is clear but not fully pinning down the operation.

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

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

The sentence 'Use this when the user wants to verify DNS configuration' is an explicit trigger condition, which is better than nothing. However, it offers no guidance on when NOT to use it, and does not route the agent to the obvious alternatives (domain_dns_list to inspect records, domain_dns_update to fix them, domain_owned_list to see which domains exist).

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantive context: the call triggers a redeploy as a side effect, returns before the build completes, and that every invocation starts a new build. That concretizes the non-idempotency in operational terms. It still does not say what happens to the old deployment or traffic during the redeploy.

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

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

Three short sentences, front-loaded with the trigger condition, then the side effect, then the async-return caveat. Nothing is redundant or padded.

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

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

With a minimal three-param schema, no output schema, and clear annotations, the description covers the essential call-time facts: what it does, that it redeploys, and that it returns before completion. Only the post-call path (how to observe the resulting build, e.g. deploy_events) and impact on the existing deployment are 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% and the description never explains project, service, or branch beyond the passing hint that the branch comes from a GitHub or Lizard Git source. Required parameter formats and any branch-name expectations are left entirely to the agent.

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 (switch the branch a service deploys from) and resource (a Lizard service's deploy branch, GitHub or Lizard Git source), and explicitly disambiguates from a local git checkout by scoping it to deploy configuration. An agent can tell from this alone that it is not a repo/VCS operation like git_status or repo_commit.

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?

"Use this when the user wants to switch which branch a Lizard service deploys from" gives a clear trigger condition. What is missing is an explicit exclusion or sibling pointer — e.g. that plain redeploys on the same branch belong to deploy_redeploy — so the agent must infer the boundary.

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

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

Annotations already establish that this is a read-only, non-destructive, idempotent operation. Beyond that, the description adds important behavioral detail: it returns an install URL that the user must open in a browser, and the flow cannot complete automatically. This is exactly the kind of context an annotations-only reading would miss.

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

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

Three short sentences, each doing distinct work: trigger condition, return/manual behavior, and exclusion case. The most important operational detail—that the URL must be opened by the user—is front-loaded after the trigger 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 zero-parameter tool with no output schema, the description supplies the necessary return-value context: an install URL. It also explains the manual browser step and the case where the tool is unnecessary, leaving no meaningful gap for invocation.

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

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

The tool takes no parameters, so there is no parameter semantics to explain. A baseline of 4 is appropriate; the description correctly does not invent parameter details.

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

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

The description states a specific action and resource: connecting a GitHub account to Lizard and returning an install URL. It is clearly distinct from repository-operation siblings like git_checkout, git_status, and repo_create, so an agent can identify its role without inspecting 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?

The opening sentence gives an explicit trigger condition: 'Use this when the user wants to connect their GitHub account to Lizard, e.g. to deploy a private GitHub repo.' It also names a clear when-not condition: 'Lizard Git repositories need no connection.'

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful scope context (it spans account-level GitHub connection state and per-service tracking). It says nothing about what the response contains or whether the call can be slow/expensive against GitHub, and there is no output schema to cover that gap.

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

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

Two sentences, no filler, with the primary trigger front-loaded and the alternative-route note trailing where it belongs. Every sentence earns its place.

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

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

For a read-only status tool with strong annotations and one parameter, the call itself is safe to make. However, an agent cannot predict the shape of the result (connection state vs. per-service repo/branch list) and gets no format hint for the project argument, both of which matter for a status-reporting tool with no output schema.

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

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

Schema description coverage is 0% for the single required 'project' parameter. The description implies that scope ('each service in a Lizard project') but never states whether the value is a project name, slug, or ID, nor what happens if the project has no GitHub-linked services. Partial compensation only.

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

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

The description states the resource precisely: the account's GitHub connection status plus the repo/branch each service in a Lizard project tracks. That is more specific than the title alone and lets an agent distinguish it from the git/repo siblings. It reads as a return-value statement rather than a crisp verb, so it stops short of a 5.

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

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

Explicit trigger ('Use this when the user wants to see...') plus an alternative route: for Lizard-hosted repos use repo_list / repo_show. That is clear when-to-use and where-else-to-go guidance. It does not state an explicit exclusion (e.g. 'do not use this to check out or connect repos'), so it is not full when/when-not coverage.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real value beyond that by clarifying the output is a 'bounded snapshot, not a live stream' — an important expectation-setting detail an agent would otherwise have to guess from the paging limit.

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 short sentences, zero waste, with the trigger condition front-loaded and the key caveat second. Nothing is repeated from the title 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 read-only tool with no output schema, the description covers the trigger and the snapshot nature, but says nothing about log line format, ordering, or what happens when no logs exist. Adequate to call correctly, but an agent must infer the return shape.

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 50% schema description coverage, three params (build, level, buildId) are documented in the schema, while project/service are self-evident strings and limit carries default/min/max. The description mentions service and build conceptually but adds no syntax, defaults, or filtering semantics beyond the schema.

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

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

States a specific verb and resource — showing recent log output from a Lizard service or build — which is clearly distinct from siblings like deploy_events or metrics_get. It does not explicitly name a sibling, but the resource is unambiguous.

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

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

The phrase 'Use this when the user wants to see recent log output' gives a concrete trigger condition, and the build qualifier narrows it further. It stops short of naming alternatives (deploy_events, ci_run_show) or exclusion cases, so it's clear context without 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the metric scope and time-range framing but says nothing about return format, granularity, or rate limits, leaving it adequate rather than 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?

A single front-loaded sentence that leads with the triggering condition and no wasted words. It could be marginally tighter but is well-structured.

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

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

For a read-only tool with no output schema and thin parameter documentation, the description explains what it fetches and over what window but omits what the response contains and how project/service resolve. Sufficient to invoke, but not fully self-contained.

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

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

With only 33% schema description coverage, the description should carry more weight. It does hint at the time-range concept and the app-vs-addon distinction (mapping loosely to project/service), but it doesn't clarify the range enum values, the default, or the required project parameter.

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

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

States a specific verb (get metrics) and resource (CPU, memory, network metrics) scoped to a Lizard app or addon over a time range. This clearly separates it from siblings like logs_tail or service_show, though it doesn't explicitly name a competing 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?

The 'Use this when the user wants...' phrasing gives a clear triggering condition tied to metric types and time range. It stops short of naming alternatives or exclusions (e.g., when to use logs_tail instead), so it lacks full routing guidance.

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

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

Annotations already flag this as a non-idempotent, destructive write, so the description doesn't need to restate that. It does add value by defining the fork syntax ('owner:branch') and the draft switch, but it omits what happens when a PR already exists for the same head/base — the key risk for a non-idempotent create.

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

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

Two sentences, no filler. The core action and the head→base direction come first, with the draft detail trailing as a secondary note.

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

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

For a six-parameter create tool with no output schema, the description covers the semantically hard parameters well. A minor gap remains around the failure mode for duplicate PRs and whether the created PR's identifier is returned, but the essentials for a correct call are present.

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

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

Schema coverage is only 17% (just repo), so the description must compensate — and it does: head accepts a branch or 'owner:branch' of a fork, base defaults to the default branch when omitted, and draft:true creates a draft. Only title and body, which are self-explanatory, are left undocumented.

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 ('Open a pull request in a Lizard Git repository') and immediately scopes it with the head→base direction. The verb alone separates it from pr_list, pr_show, and pr_merge without needing to name them.

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

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

It clarifies the head/base relationship and the default for base, which tells the agent how to invoke it, but never says when to use this versus pr_merge or pr_show, nor what precondition (an existing branch with commits) must hold. Usage is implied by the verb rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavior the schema cannot express: that results default to open PRs only unless state is overridden. It says nothing about ordering, result limits, or pagination, which is the main remaining gap.

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

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

A single compact sentence with the scope stated first and the filter behavior in a parenthetical. The clipped "closed, all" phrasing is terse to the point of being slightly telegraphic, costing a little clarity for its brevity.

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 some burden for return expectations, and it discloses neither the fields returned per PR nor any ordering/limit behavior. For a straightforward read-only list tool it is minimally sufficient, but an agent cannot predict result size or shape.

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 only 33%: repo is documented in the schema and state's default is clarified in the description, but the `query` parameter is a bare string with no documentation anywhere — the agent cannot tell whether it matches title, body, author, or branch. With coverage this low the description needed to compensate and does not.

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

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

The description gives a specific verb and resource ("List pull requests") scoped to a Lizard Git repository, which separates it from pr_create/pr_show/pr_merge by intent. It stops short of naming those siblings explicitly, so an agent must infer the list-vs-show boundary.

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

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

Usage is implied by the enumeration tool and the state filter, but there is no explicit when-to-use guidance such as "use pr_show for a single PR" or any note about paging through large result sets. The default-state note is closer to parameter guidance than selection 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?

Adds substantial context beyond annotations: the base branch moves, which can trigger a deploy or CI, and deleteBranch removes the head branch afterward. These side effects are critical for an agent to understand before invoking a destructive, non-idempotent 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?

Two tightly written sentences with zero waste. The merge method details are front-loaded, followed by the important CI/deploy warning and user-consent requirement.

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

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

The description covers the critical destructive side effects and consent requirement well. However, with five parameters and low schema description coverage, it could do more to explain the optional message parameter and confirm the role of repo/number.

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 only 20%, so the description must compensate. It explains the method options and the default, plus the effect of deleteBranch, but it omits meaning for message, number, and repo beyond what the schema already provides.

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

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

States a specific verb and resource: 'Merge a Lizard Git pull request'. It clearly distinguishes itself from sibling tools like pr_create, pr_list, pr_show, and repo_commit by focusing on the merge action.

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

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

Provides clear guidance to get the user's go-ahead first, which is important for a destructive operation. It does not explicitly compare against alternatives, but merge is a distinct action and no close sibling overlaps exist.

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

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

Annotations already flag non-idempotency and destructiveness, but the description adds concrete consequence: calling again creates another project even with the same name. That is useful elaboration beyond the hint, though it doesn't explain the destructiveHint=true profile (a create tool) or what happens to the workspace on failure.

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

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

Two tight sentences with the triggering condition front-loaded and the duplicate-creation warning immediately after. No filler.

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

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

For a two-parameter, fully described create tool with no output schema, this is nearly sufficient. It would be stronger if it told the agent what is returned (e.g., project ID) for chaining into service_create.

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

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

Schema description coverage is 100% for both parameters, so the schema carries parameter meaning. The description adds only the notion that the project is empty and name may duplicate, not format or scoping detail. Baseline 3 applies.

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

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

States a specific verb and resource ('create a brand-new empty Lizard project to hold services') and distinguishes creation from update semantics. It does not name a sibling alternative, but no other create-a-project tool exists, so the differentiation gap is minor.

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?

'Use this when the user wants to create a brand-new empty Lizard project' gives a clear triggering condition. It also warns that repeat calls make duplicates rather than updating, which is a when-not-to-use hint, though it doesn't point at a specific alternative 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?

Even though annotations already flag destructiveHint=true, the description discloses the actual blast radius: services and databases stop and linger in trash for 3 days, while sandboxes, their volumes, and snapshots are destroyed immediately with no recovery. It also prescribes telling the user both parts before asking, which annotations can't express.

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

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

Four short sentences, front-loaded with the action and its precondition, then the consequences, then the confirmation rule. Nothing repeats the name or title and 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 destructive, non-idempotent, closed-world two-parameter tool with no output schema, the description covers selection, preconditions, irreversible consequences, and user-confirmation obligations. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so both the project identifier and the confirm const are already documented in the schema. The description reinforces the confirmation gating but adds no new syntax or formatting detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource (delete a project) and immediately scopes it against the tempting wrong target: 'do not call this to delete only one service,' which distinguishes it from service_delete. An agent can pick this over service_delete or workspace_delete from the description alone.

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

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

Gives an explicit precondition ('when its owner explicitly asks'), an explicit exclusion ('do not call this to delete only one service'), and a gating requirement ('Requires the user's confirmation'). Both when-to-call and when-not-to-call are stated outright.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered. The description adds only the optional-workspace scoping note, with nothing about result limits, ordering, or pagination.

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

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

One front-loaded sentence with the trigger condition first and the filter scope second; no filler at all.

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-required-parameter, read-only list tool with full annotation coverage and no output schema, this is close to sufficient. The only omission is any hint of what a project record contains or how results are ordered.

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

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

There is a single parameter with 100% schema description coverage ('Filter to this workspace ID'), so the schema already carries the semantics. The description's 'optionally filtered to one workspace' merely restates it, which is the baseline case.

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 ('see their Lizard projects') plus the filtering scope, so the agent can tell it lists projects rather than creating/deleting them. It does not explicitly distinguish itself from the adjacent workspace_list sibling, which is the only plausible confusion.

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?

'Use this when the user wants to see their projects' gives a clear triggering intent but names no alternatives or exclusions — an agent deciding between project_list, workspace_list, and domain_owned_list gets no routing 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?

Goes well beyond the annotations by enumerating exactly what is preserved (URL, host, port, password, settings, volumes) and by disclosing that the result is partial-success aware ("what was paused and what was skipped, with why"). It adds real context to destructiveHint=true without contradicting it — scaling to 0 is disruptive but not data-destroying.

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

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

Three tight sentences, front-loaded with the trigger condition, then effect, then return semantics, then undo path. 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 one-parameter mutation with no output schema, the description covers trigger, effect, persistence guarantees, return shape, and undo path. An agent has everything needed to call it correctly and to explain the outcome to a user.

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

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

Schema coverage is 100% for the single `project` parameter, so the schema already carries the meaning. The description refers to "a Lizard project" but adds no format or scoping detail beyond what the schema states, so baseline 3 applies.

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

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

States a specific verb and resource ("stop every service of a Lizard project") plus the crucial scope qualifier "without deleting anything," which distinguishes it from project_delete. The mechanism ("each app and database scales to 0") makes the effect concrete rather than a restatement of the name.

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?

"Use this when the user wants to stop every service... without deleting anything" gives an explicit trigger condition, and "Undo with project_resume" names the reverse action. It does not explicitly route to service_pause for single-service stopping, which is the main remaining ambiguity in a very crowded sibling set.

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

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

Goes beyond the annotations by disclosing the billing-freeze exception and the return shape ('what was resumed and what was skipped, with why'), which is genuine partial-success behavior an agent needs. It does not explain why destructiveHint=true (e.g. resumed services incur billing) or whether resuming already-running services is a no-op despite idempotentHint.

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

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

Three short sentences, front-loaded with the trigger condition, then the exception, then the return value. No filler, though the 'with why' phrasing at the end is slightly informal.

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 tells the agent the result reports resumed vs skipped items and reasons, and warns about the billing-blocked case. Missing only sibling differentiation and the rationale for the destructive annotation.

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

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

Only one parameter, and the schema documents it fully (name, slug, or ID at 100% coverage). The description mentions 'a Lizard project' but adds no syntax or format guidance beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource: 'start again the services of a Lizard project' clearly scopes a project-level bulk resume. It implicitly contrasts with service_resume/workspace_resume by operating on all services of a project, but never names those siblings, so an agent must infer the granularity distinction.

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

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

'Use this when the user wants to start again the services of a Lizard project that they paused' gives a clear triggering condition, and the billing-freeze sentence states a case where the tool will not fully succeed. No explicit alternative routing (e.g. to service_resume for a single service) is provided.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotent, non-destructive, closed-world), so the description only needs to add what the call actually does. It does so by disclosing that the response aggregates conversation, head commit, mergeability, and pending branch-rule requirements — context an agent could not get from annotations alone.

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

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

One front-loaded sentence that names the action first and then the returned facets, with no filler. Every clause carries distinct 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 must convey what comes back — it names conversation, head commit, merge status, and outstanding branch rules, which is the core of what a reviewer needs. It omits basic PR metadata (title, author, state) but is otherwise sufficient for correct invocation.

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

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

Schema description coverage is only 50%: "repo" is documented in schema as "owner/name", but "number" carries no schema description and the tool description says nothing about either parameter. "number" is reasonably inferable as the PR identifier, but the description does not 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 and resource ("Read a Lizard Git pull request") and enumerates the payload: conversation, head commit, mergeability, unmet branch rules. That payload detail distinguishes it from pr_list (enumeration) and pr_merge (mutation), though it never names those siblings 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?

The word "Read" implies inspection of a single existing PR, so the use case is inferable, but there is no explicit when-to-use framing, no prerequisites, and no pointer to pr_list or pr_merge as 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the discovery-before-mutation context; it says nothing about whether the region list is static or dynamic, cached, or how it relates to existing deployed services.

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

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

A single sentence, front-loaded with the usage trigger ('Use this when...') and ending with the concrete downstream actions. Nothing extraneous.

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 no-parameter, read-only discovery tool with rich annotations and no output schema, the description covers the essential purpose and timing. The one remaining gap is that it doesn't hint at the return contents (region identifiers), which matters because no output schema exists to document them.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. No misleading parameter language is present.

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 makes clear this returns the set of available deployment regions, which is a specific verb+resource rather than a restatement of the name. It doesn't explicitly state the shape of what comes back (names vs. slugs), so it falls short of a 5, but an agent can distinguish it from siblings like service_list or template_list without opening a schema.

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

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

It gives an explicit trigger — call this before creating a service or addon — which ties the tool to concrete downstream siblings. There is no explicit exclusion or statement about when it's unnecessary (it is safe and idempotent, so it could be called freely), leaving that to inference.

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

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

Goes well beyond the annotations by disclosing side effects an agent could not otherwise predict: a commit to a deployed branch starts a deploy, a commit to a branch with .lizard/workflows starts CI, and a conflicting expect produces a 409 listing the conflicting paths. It also explains the merge-on-move semantics and the idempotencyKey retry behavior, which is consistent with (not contradictory to) idempotentHint=false.

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, with the core operation first and conditional behaviors after. The single packed paragraph makes the several distinct modes (createFrom, expect, idempotencyKey, deploy/CI triggers) harder to scan than a short clause list would be, 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?

For a destructive, 7-parameter mutation with no output schema, it covers conflict handling, retries, and downstream triggers thoroughly. The one gap is that it does not say what the call returns (commit sha, merged result, deploy/CI identifiers), which the agent must guess despite there being no output schema to consult.

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 14%, so the description has to carry the load and does: it defines the three file entry modes (new text content, delete: true, rename via moveFrom), explains createFrom as branch-creation-from-ref, and defines expect as 'the commit you based the change on'. Only branch and message are left implicit, and those are self-evident.

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 ('Commit changes to a branch of a Lizard Git repository') and immediately scopes it with 'made on the server (no clone needed)', which separates it from git_checkout/git_status-style siblings. An agent can tell from the first clause exactly what operation this performs.

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 situational guidance: use it when you don't want a clone, pass idempotencyKey for safe retries, pass createFrom when the branch may not exist, and pass expect to get server-side merge instead of a failure. It does not, however, compare against alternatives like pr_create or sandbox_write_file for editing repository content, so routing between those paths is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds useful defaults (ref omitted -> default branch) and the optional path filter, but says nothing about ordering ('recent' is undefined), page size, or pagination behavior despite a page parameter.

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

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

Two tight sentences, front-loaded with the core action and scope. The docs URL is minor overhead but reasonable; nothing is redundant.

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

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

For a simple read-only listing tool with annotations carrying the safety profile, the description covers the essential calling semantics (ref default, path filter). Gaps remain around the undocumented page parameter and the shape/ordering of returned commit entries, since no output schema exists.

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 only 25% (only repo documented), so the description has to compensate. It does explain ref (defaults to default branch) and path (only commits touching it), but the page parameter is never mentioned in either schema or description — a real documentation hole.

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 ('List recent commits of a Lizard Git repository') with clear scope modifiers (at a ref, optionally restricted to a path). This distinguishes it in practice from siblings like repo_commit and repo_show, though it never names an alternative 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?

Implies when to use it via the ref/path scoping, and clarifies the default-branch fallback when ref is omitted. But it never says when to prefer repo_show, repo_commit, or another history tool, nor any exclusions.

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

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

Annotations declare destructive/non-idempotent/non-readonly, and the description adds real behavior beyond them: default privacy, empty repo until first repo_commit unless readme:true, and collaborator inheritance from workspace. It does not disclose failure modes such as name collisions or permission requirements, keeping it short of a 5.

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

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

Four dense sentences, front-loaded with the core action and default behavior, then options, then the deployment follow-up. No filler; every clause carries actionable 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?

No output schema and 6 parameters at 33% coverage, so the description should do more. It covers the main options and the post-create deploy path but omits return values, name-format constraints, and the meaning of defaultBranch/description.

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 only 33%, so the description must compensate. It meaningfully explains readme and workspace semantics, but leaves defaultBranch and description unexplained, and the name pattern is only in the schema.

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

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

States a specific verb and resource ('Create a Lizard Git repository'), clearly distinct from sibling read tools like repo_show/repo_list. It does not explicitly contrast with other create tools (workspace_create, service_create), but the verb+resource is unambiguous.

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

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

Gives concrete selection guidance: private by default, readme:true to seed content, workspace to grant collaborators, and explicit next-step routing ('To deploy it, service_create with repoUrl lizard:owner/name'). It lacks explicit when-not-to-use or alternatives for repo creation itself.

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

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

Annotations already flag destructiveHint=true, but the description adds real value beyond them: the exact collateral damage (branches, issues, pull requests, CI runs), the downstream consequence (services deploying from it stop getting new deploys), the privilege bar, and irreversibility. That is exactly the context an agent needs before an irreversible write.

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

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

Three short sentences, front-loaded with the destructive scope, then consequences, then preconditions. Every sentence carries distinct information and none repeat structured fields.

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

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

For a two-parameter irreversible delete with no output schema, the description covers blast radius, side effects, permissions, and consent. Nothing material an agent needs to call this safely is missing.

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

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

Schema coverage is 50%: 'repo' is documented with a pattern and a repo_list reference, while 'confirm' only carries const:true. The description never mentions either parameter, though 'Get the user's approval first' loosely maps to the confirm gate. It neither adds format guidance nor compensates for the undocumented confirm flag.

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

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

States a precise verb and resource ('Permanently delete a Lizard Git repository') and enumerates the cascaded contents. This clearly distinguishes it from sibling deletion tools that target projects, services, workspaces, volumes, or sandboxes rather than Git repositories.

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

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

Gives an actionable precondition ('Owner or admin only') and an approval requirement ('Get the user's approval first'). It lacks an explicit contrast with adjacent destructive siblings such as project_delete or service_delete, so the agent must infer which resource type is being removed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds real context beyond them: default root path, ref accepts branch/tag/commit and falls back to the default branch, and the recursive behavior switch. It notes the backing API and docs link but omits return shape or pagination.

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 defaults and the recursive flag, all in one dense sentence plus a docs pointer. Efficient, though the nested parentheticals make it slightly packed.

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 should ideally hint at what a listing looks like; it doesn't. Otherwise, for a 4-param read tool with annotations already covering safety, it supplies enough to call 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 only 25% (just repo), so the description carries the burden and largely does: it explains path defaults to root, ref accepts branch/tag/commit with branch fallback, and recursive lists all file paths. Only the repo param itself is not covered here, but the schema documents it.

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

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

Specific verb and resource: 'List a folder of a Lizard Git repository ... at a ref', with the recursive variant named. An agent can tell it apart from repo_read_file by the folder-listing framing, though no sibling is 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?

It states defaults (path defaults to root, ref defaults to branch) and that recursive:true changes the result to every file path, which is usage-relevant. But there is no guidance on when to use this versus repo_read_file, repo_commits, or repo_show.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the description's job is to add beyond that — and it does: the default result set (owned + collaborated repos) and the auth constraint that 'Lizard Git refuses API keys with scopes'. Neither is derivable from annotations or schema. Return shape and pagination remain undisclosed.

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

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

Three compact sentences with no filler, and the platform clarification plus default scope come first. The semicolon-chained parameter clauses are dense but readable and each sentence earns its place.

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

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

For a two-optional-parameter list tool with no output schema and full annotation coverage, the description covers platform, default scope, filtering, and an auth caveat. Missing only pagination/result-size behavior, which is a minor gap at this complexity.

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

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

Schema description coverage is 0%, so the description must carry the parameters, and it explains both: owner narrows to a single owner, query searches names and descriptions. It stops short of saying whether the two combine or how matching works, so it is good but not exhaustive compensation.

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

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

States a specific verb and resource (list Lizard Git repositories) and explicitly disambiguates the platform from GitHub, which matters given the sibling set spans domains, services, and sandboxes. It does not name a sibling alternative such as repo_show, so it falls short of a 5.

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

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

The default scoping ('the user's own and the ones they collaborate on') implies when this tool is the right entry point, but there is no explicit statement of when to prefer repo_show or pr_list instead, and no exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behaviour, so the safety profile is covered. The description adds real context beyond that: the 64 KiB truncation threshold and the fact that binary or oversized files return size only, which an agent cannot learn from annotations. Return format for partial reads is still unstated.

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

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

Two compact sentences, front-loaded with the core action and the ref default, followed by the size/binary caveat and a docs pointer. Nothing is redundant, though the trailing API/docs sentence is low value for an agent already in the tool.

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

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

For a 3-parameter read tool with full annotation coverage and no output schema, the essentials are present: default ref behaviour, size ceiling, and binary handling. Missing guidance on which sibling to use and on 'path' formatting keeps it short of complete.

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

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

Schema coverage is only 33% – just 'repo' is documented (owner/name with a reference to repo_list). The description partially compensates by explaining that 'ref' defaults to the default branch when omitted, but 'path' semantics (leading slash, directory rejection, encoding) are 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?

The description states a specific verb and resource ('Read a text file from a Lizard Git repository at a ref') and pins the scope with the 64 KiB cap and binary fallback. It implicitly distinguishes itself from the listing sibling (repo_files) by emphasizing single-file content retrieval, but never names that alternative outright.

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

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

Usage is only implied: an agent can infer this is the way to fetch file contents rather than list them. There is no explicit 'use this when…' or routing to repo_files / repo_commits / sandbox_read_file, so the choice among near-neighbours is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds real value by disclosing what the response contains (role, visibility, empty flag, counts), which is the main behavioral fact an agent needs and which 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?

One compact sentence, front-loaded with the verb and resource, then the payload fields. 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?

Since there is no output schema, naming the returned fields in the description is exactly the right compensation and makes the tool callable without guesswork. Only minor gaps remain: error behavior for missing/inaccessible repos is 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 coverage is 100% and the single 'repo' parameter is documented with the 'owner/name' pattern plus a pointer to repo_list. The description adds no further syntax or format meaning, so baseline 3 applies.

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

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

States a specific verb ('Read') and resource ('a Lizard Git repository's details') and enumerates the concrete fields returned: default branch, visibility, user role, empty flag, branch and issue/PR counts. This makes it clearly the single-repo detail reader, distinct from repo_list/repo_files/pr_list 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?

Usage is only implied: it takes an owner/name identifier, so an agent infers it is for inspecting one known repo. There is no explicit when-to-use vs repo_list/repo_files, no note about access requirements for private repos, and no mention of behavior on a nonexistent 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?

Goes well beyond the annotations: billed cloud resources, the 5-minute default lifetime and that expiry deletes files unless a volume is attached, that no host files/env vars/API key are copied in, and that the server validates template names. The destructiveHint=true annotation is corroborated and explained by the lifetime-deletion behavior.

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

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

Front-loaded with definition, defaults, and options in a compact sequence; every sentence carries information. It is dense to the point of being slightly packed (parenthetical template list mid-sentence), but there is no filler.

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

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

For an 8-parameter, non-idempotent, billed mutation with no output schema, it covers cost, lifetime, deletion semantics, isolation, approval gating, and return value (the ID). Minor gaps remain: it does not describe behavior on name conflicts or how a failed creation affects volume/snapshot state.

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?

Adds meaning the schema alone lacks: the enumerated valid template names, the meaning of each size in vCPU/RAM, the interaction rule that snapshotId keeps the snapshot's size so size must be omitted, and that region defaults to the volume's or snapshot's region. Schema coverage is 75%, and the description fills the remaining gaps rather than restating enum values.

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 and immediately defines the resource: "Create a sandbox (a Firecracker microVM) in an explicit project." It also distinguishes it from sibling creation paths by noting snapshotId starts from a saved snapshot (as opposed to sandbox_snapshot/sandbox_fork) and that it returns an ID.

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

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

Gives concrete selection guidance: pass snapshotId to start from a snapshot (and then leave size out), pass volume to mount a persistent volume, plus defaults for template and size. It also states a real precondition ("Get the user's approval before creating it") and a caution ("do not retry an uncertain response blindly"). It does not explicitly name sibling alternatives such as sandbox_fork for cloning an existing sandbox, which keeps it from a 5.

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

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

Annotations already flag destructiveHint=true, but the description adds the details an agent actually needs: permanence, that all files inside the sandbox are destroyed, that an attached volume survives, and that a human approval step is required first. That is meaningful context beyond the annotation flags.

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

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

Four short sentences, front-loaded with the destructive scope, then the approval requirement, then the use case, then the exclusions. No filler and no repetition of the title.

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

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

For a 2-parameter destructive tool with rich annotations, this covers destruction scope, surviving resources, and the approval prerequisite, which is what an agent needs before calling. The only omission is any mention of the required confirm flag or what the call returns on success/failure.

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%: sandboxId is documented in-schema with its source, while 'confirm' is only a const true with no prose. The description never mentions the confirm gate, which is the one non-obvious argument, so it adds nothing over the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Permanently destroy one sandbox and all its files') and immediately bounds the blast radius with '(an attached volume stays)'. It also distinguishes itself from project_delete and service_delete by saying it does not delete the project or app services.

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

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

Gives an explicit when-to-use ('clean up a sandbox created for a task') plus an explicit when-not ('Does not delete its project or any app services'), which implicitly routes project-level teardown to project_delete. It doesn't name that sibling tool outright, keeping it just 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?

Goes well beyond the destructiveHint=true annotation by spelling out exactly what is destroyed (the whole sandbox and all its files), which triggers it (cancellation, timeout, failed request) versus which does not (a nonzero exit code), that approval is required, and the 64 KiB per-stream output cap. This is unusually complete disclosure for a destructive 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-loads what the tool does, then each subsequent sentence carries a distinct load-bearing fact: approval, destruction rules, sandbox selection, output cap, retry caution. No filler or restatement of the title.

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 six-parameter destructive tool with no output schema, the description covers the critical risks and the output cap, which implies stdout/stderr streams. It leaves the return shape (exit code field, truncation indicator) and the cwd/envs parameters unaddressed, which is a modest but real gap.

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

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

Schema coverage is 50%, and the description compensates for confirm (approval implies sandbox loss) and timeoutMs (timeout destroys the sandbox), plus the sandboxId scoping via 'existing sandbox'. But cwd and envs — including the nested-object env var pattern constraints — get no mention in either the schema or the description.

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

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

States a specific verb and resource: run a shell command, as root, inside an *existing* sandbox. That scope wording separates it from sandbox_create and the file-oriented siblings (sandbox_read_file, sandbox_write_file) without the agent needing to open 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 a clear operating condition — 'Use an ephemeral sandbox created for this task' — and a caution against blind retries after failure. It stops short of explicitly naming which sibling to use for non-shell file operations or when a fork/snapshot is preferable, so alternatives are 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?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true) by explaining the security model: the URL carries an access token, browsers get a cookie, non-browser clients send X-Lizard-Access-Token, and anyone holding the URL or token can reach the port. The 'share it only with the user' warning aligns with and gives substance to the destructive and open-world 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?

Front-loaded with the action and use case, then layered: prerequisite, token semantics, sharing warning, teardown pointer. Every sentence carries distinct operational 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 (a URL plus accessToken) and how it is consumed. Combined with the precondition and the teardown sibling, an agent has everything needed to call this correctly and safely.

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

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

With only 50% schema coverage (sandboxId is documented, port is not), the description partly compensates by stating the port must be listening on 0.0.0.0 – a real success precondition tied to the parameter. It doesn't explain anything further about port selection or reuse of an already-exposed port, so it stops short of fully covering the 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 and resource ('Give a port inside a running sandbox an HTTPS URL') and immediately clarifies the intent with a concrete use case (showing the user a web app). It also names the sibling tool that reverses the operation, so it is distinguishable from sandbox_unexpose_port 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 frames when to use it ('to show the user a web app the sandbox runs'), states the precondition that the process must listen on 0.0.0.0, and names the alternative for teardown (sandbox_unexpose_port). Nothing about routing is left to inference.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: the source pauses momentarily but survives, each copy is separately billed and limit-counted, partial success is possible with one entry per copy ('a sandbox or an error'), and copies inherit the source lifetime unless lifetimeMs is set. That is exactly the mutation side-effect detail an agent needs.

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

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

Five short sentences, all load-bearing, with the core action front-loaded and the safety gate (user approval) placed last as a final check. Dense but never padded; only slight cost is the packing of billing and limit behavior into one sentence.

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 supplies the return shape (one entry per copy, sandbox or error), plus billing, lifetime, and limit semantics. Minor gaps remain – no cost guidance for large counts and no statement of what state a fork starts in – but an agent can invoke this correctly.

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

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

Schema description coverage is only 25%, so the description carries weight; it does explain lifetimeMs (inherits source lifetime unless given) and hints at count through 'one entry per copy' and 'only some may start'. However, count is never explicitly stated as the number of copies to create and confirm is only obliquely covered by 'Get the user's approval first', leaving half the parameters under-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 and resource – 'Start live copies of a running sandbox: memory, processes and files' – which cleanly separates it from sandbox_snapshot (state capture) and sandbox_create (blank sandbox). The 'live copies ... memory, processes and files' phrasing tells an agent exactly what is duplicated.

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 preconditions: source must be running, the user must approve first, and copies count against running-sandbox limits so bulk forks may partially fail. It does not name the alternative tools (snapshot vs. create) an agent might pick instead, but the operational 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, idempotentHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context (separate resource domain, IDs reusable by other sandbox tools) but says nothing about pagination, ordering, or result volume for what could be a large list.

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 short sentences, front-loaded with the action and scope, then the follow-on usage note. No filler and nothing buried.

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 adequately implies the return shape (a list of sandboxes whose IDs feed other sandbox tools). The only real gap is the unexplained project identifier format, which is a parameter-level rather than contextual omission.

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 parameter burden and largely fails to. 'In an explicit project' signals that project scoping is mandatory but never says whether the value is a name, slug, or ID, nor gives format or an example. The agent is left to guess the identifier form from sibling tools.

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

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

States a specific verb and resource ('List Lizard Sandboxes') plus a scope ('in an explicit project'), so the agent knows exactly what the call returns. It also pre-empts confusion with the service_* family by noting these resources are separate from app services, though it doesn't distinguish itself from near-siblings like sandbox_snapshot_list or sandbox_list_files.

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?

'Use the returned IDs with sandbox tools' gives a clear next-step workflow, which is genuine usage guidance. However, there is no statement of when to prefer this over sandbox_show or the other listing tools, and no prerequisites or exclusions beyond the services distinction.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope and return-entry details, but does not disclose error behavior, pagination, hidden-file handling, or symlink behavior.

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

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

Two compact sentences with no wasted text. The core action and scope are front-loaded, followed by path resolution and documentation context.

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

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

For a simple read-only listing tool with rich annotations and no output schema, the description covers the key return fields and path semantics. It could be slightly more complete by noting whether listing is recursive or how missing paths are handled.

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 only 50%: sandboxId is documented in the schema, while path is not. The description compensates meaningfully for path by explaining that relative paths start at /workspace, though it does not mention the default or absolute-path handling.

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

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

The description states a specific verb and resource: listing one directory inside a sandbox. It also names the fields returned (name, path, type, size), which distinguishes it from siblings like sandbox_read_file or sandbox_exec.

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

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

The phrase 'List one directory' implies non-recursive directory listing, and the relative-path note gives useful context. However, it does not explicitly say when to use this instead of sandbox_read_file or sandbox_exec, nor does it state exclusions or prerequisites.

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=true and idempotentHint=true already declared, the description adds real substance: stored-state-only billing, exemption from the running-sandbox limit, a 2-minute wait ceiling, and the reversibility path via sandbox_resume. It does not say what happens if pausing exceeds the 2-minute window or how in-flight exec sessions are treated, which leaves the main operational edge case unresolved.

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

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

Four short sentences, each carrying distinct information: what it does, cost implications, timing limit, and reversal. Front-loaded with the action and no filler.

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

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

For a one-parameter mutating tool with annotations and no output schema, the description covers cost, limits, latency, and undo. The only meaningful gap is post-timeout behavior (error vs. eventual completion), which an agent would want before relying on the 2-minute guarantee.

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

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

There is a single parameter with 100% schema coverage, including a pattern, length bounds, and a description pointing at sandbox_create/sandbox_list as sources. The prose adds nothing about sandboxId, so baseline 3 applies.

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

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

States a specific verb chain ('save memory, processes and files, and stop it') against a specific resource (sandbox), which precisely separates it from sandbox_resume (the inverse) and sandbox_snapshot (which saves state but does not stop the sandbox). An agent can route correctly from the first sentence alone.

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

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

The closing sentence 'Undo with sandbox_resume' gives the explicit inverse operation, and the cost/limit sentence implies when pausing is preferable to deleting. It stops short of naming when to prefer sandbox_snapshot or sandbox_delete over pausing, so the alternative routing is only partial.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description correctly focuses on what annotations cannot express: the 64 KiB read cap, UTF-8-only constraint, and relative-path resolution against /workspace. It stops short of stating what happens on truncation or non-UTF-8 input (error vs partial content).

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

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

Three short sentences, front-loaded with the core action and cap, followed by path resolution and the remote/local distinction. The docs URL is the only debatable element and is cheap. Nothing is redundant.

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

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

For a two-parameter read tool with a read-only annotation profile and no output schema, the description covers the key risks (remote vs local, size cap, encoding). The one gap is that it never describes the return payload shape or truncation signalling, which the absent output schema leaves 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 coverage is 50%: sandboxId is documented in the schema but path is not. The description compensates by defining path semantics (relative paths start at /workspace, remote resolution), which is exactly the gap the schema leaves. It adds no detail beyond the schema for sandboxId, but that field is already covered.

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

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

States a specific verb and resource ('Read up to 64 KiB of UTF-8 text from a sandbox') with scope qualifiers (size cap, encoding). The sentence clarifying that paths refer to the remote sandbox, never the MCP server's files, separates it from repo_read_file and from any local-file interpretation.

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

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

Usage is implied by the remote-sandbox scoping, but there is no explicit routing guidance such as 'use sandbox_list_files to discover paths first' or 'use repo_read_file for repo contents'. The agent must infer when this beats sandbox_exec or sandbox_list_files.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=true), and the description adds genuinely non-obvious behavior: it blocks for up to 2 minutes, the sandbox resumes with preserved memory/processes/files, and a failed resume preserves state rather than destroying it. It does not reconcile the destructiveHint=true flag with that 'state is kept' reassurance, leaving mild ambiguity about what is actually at risk.

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

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

Three short sentences, front-loaded with the action and its state-preservation guarantee, followed by the blocking behavior and the failure/retry note. No filler and nothing buried.

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-param tool with full schema coverage and annotations, this covers the operationally important facts: blocking duration, state preservation, and failure handling. It would be complete with a note on what a successful resume returns (status/connection info) since no output schema exists.

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

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

Only one parameter (sandboxId) and schema coverage is 100%, with the schema itself explaining it is the exact ID from sandbox_create or sandbox_list. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb (start/resume) and resource (paused sandbox), and adds the crucial scope detail that it resumes 'where it left off: same memory, processes and files.' That framing cleanly distinguishes it from sandbox_pause, sandbox_fork, and workspace_resume without needing their schemas.

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

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

'Start a paused sandbox again' implicitly scopes usage to paused sandboxes, and the closing 'If resuming fails, the saved state is kept; try again' gives explicit retry guidance. It stops short of naming an alternative (e.g., sandbox_create if the sandbox is gone) or stating what to do if the 2-minute wait times out.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the description's real value is the consequence detail: the sandbox stops and loses its files, except for an attached volume. That is genuinely beyond the annotations. It doesn't address edge cases such as whether this works on an already-paused sandbox or how the server resolves competing timeout changes.

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

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

Three short sentences: effect first, usage second, constraint last. Every clause carries information — consequence, intent, and range — with no padding.

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

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

For a two-parameter mutation with annotations covering idempotency and destructiveness and no output schema, the description supplies the missing pieces: relative timing, file-loss behavior, and units/range. Only minor operational context (permissions, behavior on paused sandboxes, error conditions) is absent.

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

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

Schema coverage is 50%: sandboxId is documented but lifetimeMs has only bare numeric bounds. The description compensates well by naming units (ms) and the range 60,000–86,400,000 with the '(a day)' anchor, though it doesn't explain what happens if the new lifetime is shorter than the elapsed time.

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 (change sandbox lifetime) and clarifies the change is measured 'from now', which is a non-obvious semantic. It does not explicitly distinguish itself from siblings like sandbox_pause or sandbox_delete, which also terminate/limit a sandbox, so an agent must infer the boundary.

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?

'Use it to keep a sandbox the user still needs, or to end one sooner' gives clear positive usage contexts for both directions of adjustment. It stops short of naming the alternatives (pause vs. delete) an agent should consider when the intent is stopping rather than rescheduling.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, lowering the bar. The description adds meaningful behavioral context beyond them: it discloses that access to the ID is checked by the platform and enumerates the status fields returned. It does not describe behavior when the sandbox is missing or access is denied.

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

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

Two sentences, front-loaded with the read action and the fields returned, with no filler. The truncated status list ('running, pausing, paused, resuming, ...') is slightly imprecise but compact.

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

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

For a one-parameter read tool with full schema coverage and strong annotations, this is nearly complete: it conveys what is read and the authorization check. Missing only not-found/unauthorized behavior and any mention of output shape beyond the listed fields.

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

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

Schema description coverage is 100%, and the sandboxId field already explains it must be an exact ID from sandbox_create or sandbox_list. The description adds only the access-check note on 'this ID' and does not add format or constraint detail beyond the schema.

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

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

States a specific verb (Read) and resource (sandbox) and enumerates the fields returned (status, project, template, size, expiry). It implicitly distinguishes itself from sandbox_list by operating on one sandbox, but never names or contrasts with sibling tools.

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

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

Usage is implied by 'Read a sandbox's status ...' and the schema note that sandboxId comes from sandbox_create or sandbox_list, but there is no explicit when-to-use or exclusion guidance versus siblings like sandbox_list.

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: the source sandbox keeps running, storage is billed until the snapshot is deleted, the call blocks up to 2 minutes, and a large snapshot may still be processing afterward. That last caveat is exactly the kind of async-completion detail an agent needs and that destructiveHint/idempotentHint 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?

Front-loaded with the core action and result, then layered with scope, billing, and completion caveats in a logical order. Four dense sentences with no outright filler, though the scope clause is slightly compressed for the amount of meaning it carries.

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

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

Covers the mutation's side effects, lifetime, restore boundary, and the delayed-readiness problem, with a pointer to sandbox_snapshot_list since no output schema exists. Only minor gap is not saying what the call itself returns (e.g., a snapshot ID) versus what must be discovered via the list tool.

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

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

Schema coverage is 67%: name and sandboxId are self-explanatory, but the scope enum is undocumented in the schema. The description fills that gap by defining user (any of your projects), workspace, and project as restore boundaries, which is real added meaning.

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

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

States a specific verb+resource (save a running sandbox as a private snapshot) and the exact contents captured (memory and processes). It also names the downstream consumer (sandbox_create with snapshotId) and the follow-up check (sandbox_snapshot_list), so an agent can place it precisely among the sandbox_* 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?

Explains the intended use (create a reusable image to start new sandboxes) and clarifies scope semantics and billing lifetime. It does not explicitly contrast with sandbox_fork or sandbox_pause/resume, which are the nearest alternatives, so the when-not guidance is incomplete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds real value: the deletion is permanent/irreversible, and derived running sandboxes are not affected. The one remaining gap is failure behavior for an unknown snapshotId, which is not addressed.

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

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

Three short sentences, front-loaded with the action and its permanence, then the blast radius, then the prerequisite. Zero 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 destructive tool with no output schema, the description covers permanence, side effects, and the approval gate, which is most of what an agent needs. It could add what happens on a nonexistent or already-deleted ID, but that is a minor omission.

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%; the snapshotId description in the schema is already strong, but the 'confirm' parameter has no schema description at all, and the description implicitly gives it meaning by demanding user approval first — the agent can connect confirm=true to that requirement. It stops short of explicitly naming confirm, so 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 a specific verb ('Permanently delete') and a precisely scoped resource ('a saved sandbox snapshot'), and immediately clarifies that sandboxes already started from it are unaffected — which is exactly what separates this from sandbox_delete. An agent can distinguish it from sandbox_snapshot, sandbox_snapshot_list, and sandbox_delete 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?

Provides one concrete gating instruction ('Get the user's approval first') and one scoping note (running sandboxes survive), which implies it is safe to use only for cleanup of unused snapshots. However, it never routes the agent explicitly — no 'use sandbox_snapshot_list to find the ID' or 'use sandbox_delete to remove the running sandbox instead'. Usage is inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds the return field set, which is useful, but says nothing about pagination, ordering, or volume of 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?

A single front-loaded sentence with the verb first and the return fields enumerated; 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?

With no output schema, listing the returned fields is genuinely helpful. However, for a list tool the description omits result volume/ordering and any hint that the project identifier format matters, leaving gaps an agent must guess at.

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

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

The schema has one required parameter with 0% description coverage. The description's phrase 'of a project' loosely maps to it but does not say whether it accepts a project name, slug, or ID, nor any format constraints.

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

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

States a specific verb (List) and resource (saved sandbox snapshots of a project), plus the fields returned. It implicitly separates itself from sandbox_list (running sandboxes) and sandbox_snapshot (creation) but never names those siblings 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?

No guidance on when to call this versus sandbox_list, sandbox_show, or sandbox_snapshot, and no prerequisites or exclusions. The agent must infer the distinction from the word 'snapshots' alone.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description adds genuinely new behavioral facts: the access token is invalidated and the underlying process survives. It stops short of saying whether re-exposing issues a fresh token or whether calling on a non-exposed port errors.

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 clauses separated by a semicolon, with the primary effect front-loaded and the non-obvious side effect second. Every phrase carries information.

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

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

For a 2-parameter destructive tool with full annotation coverage and no output schema, the description supplies the essential effects (URL gone, token dead, process alive). Only edge-case behavior — idempotent re-calls on an unexposed port, and whether the port param must match an existing exposure — 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 coverage is only 50%: sandboxId is documented in-schema while 'port' has no description beyond numeric bounds. The description says 'a sandbox port' but adds no format, range, or lookup guidance (e.g. from sandbox_show) to compensate for the undocumented parameter.

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

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

States a specific verb (Remove) and resource (the HTTPS URL of a sandbox port), which unambiguously makes it the inverse of the sibling sandbox_expose_port. It stops short of naming the sibling pair explicitly, but the operation is still instantly identifiable.

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

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

The clarifier 'the process inside keeps running' implicitly steers an agent away from this tool when the goal is to terminate the sandbox (use sandbox_delete instead), but no alternative is named and no explicit when/when-not condition is given. Usage must be inferred from the effect description.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: the 64 KiB ceiling, UTF-8 encoding, mandatory user approval, and the explicit assurance that it does not touch the MCP server's filesystem. The unexplained overwrite-vs-create semantics is the only real gap.

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