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

Even though destructiveHint is already true, the description goes beyond the annotation by spelling out concrete effects: site goes offline, address is released, data is destroyed, and the operation cannot be undone. It also instructs the agent that user confirmation is required, which is exactly behavioral disclosure 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?

Three short sentences, each earning its place. The core purpose is front-loaded, consequences are listed compactly, and the confirmation requirement closes the definition without 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 one-parameter destructive action with no output schema, the description plus annotations fully cover what an agent needs: what happens, irreversibility, and the necessary confirmation step before invocation.

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

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

Schema description coverage is 100%: the only parameter, `id`, is already described as 'Project identifier'. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description opens with the specific action 'Permanently delete a project' and names the concrete consequences: site goes offline, address released, data destroyed. This is unambiguous and clearly separates it from siblings like update_site, deploy, or 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?

The description gives explicit context: this is a permanent deletion and the caller must ask the user to confirm before invoking. It does not explicitly name alternatives or say when not to use it, but the destructive framing and confirmation requirement provide clear operational 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 indicate this is a mutating, non-idempotent operation, so the description doesn't need to restate that. It adds valuable behavioral context beyond the annotations: the build happens asynchronously after the call returns, the final URL is returned immediately, and the build takes one to two minutes. It also discloses that a second call creates a second project and consumes quota, which is a meaningful side effect. The only minor gap is that it doesn't explicitly state whether the operation is reversible, but the description already covers the most important behavioral traits.

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

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

The description is a single dense paragraph that front-loads the core purpose and then covers usage, behavior, and alternatives. Every sentence earns its place, and the most important information (what the tool does, how to provide code) comes first. It is slightly long, but the length is justified by the number of parameters and the need to explain the async build behavior and the sibling distinction.

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

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

For a tool with seven parameters, no output schema, and a non-trivial async behavior, the description is remarkably complete. It covers the two mutually exclusive input modes, the default for `directory`, the subdomain logic, the static-site detection, the return behavior, the polling mechanism, and the alternative tool for updates. An agent has everything it needs to invoke this tool correctly and to know what to expect afterward.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description adds meaning beyond the schema by explaining the relationship between `name` and `slug` (name becomes subdomain unless slug says otherwise), the mutual exclusivity of `repo` and `directory`, and the default behavior of `directory` (defaults to current folder). It also clarifies that `port` is ignored for static sites and that `family` maps to pricing tiers. This is a strong complement to the schema, though the schema already carries the baseline.

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

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

The description states a specific verb ('Create a new project'), a resource ('on Swigs Cloud'), and the outcome ('put it online over HTTPS, hosted in Switzerland'). It also distinguishes itself from the sibling `update_site` by explicitly saying that calling `deploy` again creates a second project rather than updating an existing one. This makes the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: use exactly one of `repo` or `directory`, and it names the alternative for changing an existing site (`update_site`). It also explains the deployment flow (returns immediately, poll `project_status`) and the quota consequence of calling `deploy` again, which is exactly the kind of usage context an agent needs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'your projects' scope and output field names, but no additional behavioral traits like pagination, error cases, or limitations.

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 states the action, scope, and output fields with no wasted words. Every part of the description earns its place.

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

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

For a simple, parameterless list tool, the description provides the action, ownership scope, and expected output fields, which is sufficient for basic invocation. It could mention pagination or limits, but the lack of parameters and simple listing nature make the gaps minor.

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

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

The tool has zero parameters, so there is no parameter meaning beyond the schema to convey. The description's field list describes output rather than parameters, which is acceptable given the empty input schema.

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

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

The description states a specific verb and resource: 'List your Swigs Cloud projects', and it names the returned fields. It is clear and distinct from mutating sibling tools, though it does not explicitly contrast itself with the similarly named project_status 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?

No guidance is given about when to choose list_projects over alternatives like project_status or logs. The description only states what the tool does, leaving the agent to infer the right context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful scoping context ('latest deployment' and the failure trigger), but it does not describe what the returned log contains or whether it reflects full logs or a summary.

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, no filler, and the trigger condition is delivered immediately after the purpose. Every word 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 tool with one documented parameter, a clear trigger, and full annotation coverage, the description is complete. An agent can determine when and how to invoke it without additional information.

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

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

The schema fully documents the single 'id' parameter as 'Project identifier', so the description does not need to add much. It adds no extra meaning about the parameter beyond what the schema already provides, matching the baseline for high schema coverage.

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

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

The description identifies a specific resource ('log of the latest deployment') and a clear trigger condition, which distinguishes it from sibling tools like deploy and project_status. However, the leading phrase 'Build log' is slightly ambiguous as to whether 'build' is a verb or part of a noun phrase, so it is not maximally explicit.

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

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

It gives an explicit, actionable instruction: call it when project_status reports 'failed'. This is clear context for when to use the tool, though it does not describe when not to use it or mention alternatives such as redeploy.

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

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

Annotations already indicate that the tool is read-only, idempotent, and non-destructive, so the behavior burden on the description is lower. The description still adds meaningful behavioral context by defining the possible state values and what they mean, and by telling the agent which follow-up action to take on `failed`.

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 yet complete: two sentences convey the state vocabulary and the failure follow-up with no filler or repetition. The key purpose is front-loaded, and the follow-up instruction is placed exactly where relevant.

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

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

For a single-parameter read-only status tool with no output schema, the description fully compensates by explaining the expected output states and their meaning. Nothing is missing for an agent to correctly call the tool and interpret its result.

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

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

The schema fully documents the single parameter `id`, including where it comes from (`deploy` or `list_projects`), so schema coverage is 100%. The description does not add parameter-level meaning beyond that, which is fine because the schema already carries the necessary semantics.

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

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

The description clearly identifies the tool's purpose: it returns the state of a single project. It goes beyond a bare statement by explaining what each state means, and it distinguishes itself from siblings like `list_projects` by narrowing scope to 'one project' and from `logs` by mentioning logs only as a follow-up.

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

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

The description gives clear context for when to use the tool: to check the status of one project and determine whether it is live, failed, or still building. It also routes the agent to `logs` when the state is `failed`, which is a concrete conditional next step, though it does not explicitly enumerate exclusions for sibling tools like `redeploy` or `set_env`.

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 is not required to restate that this is a mutating operation. The description adds useful behavioral context: it rebuilds from current source and preserves the address. It does not detail side effects like downtime or environment changes, but the annotations plus the address-stability note cover the key behavioral traits.

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

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

Three sentences, each earning its place: what it does, when to use it, and a key behavioral guarantee. No fluff or repetition of schema/annotation content.

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

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

For a single-parameter tool with annotations covering the destructive nature, the description is nearly complete. It explains the purpose, the trigger conditions, and the address stability. It does not mention whether the operation is synchronous or how to check status, but the sibling project_status tool likely covers that, so this is a minor 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 description coverage is 100% for the single 'id' parameter, so the schema already documents it as a project identifier. The description does not add further parameter-level detail, but with full coverage the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Build and deploy'), a clear resource ('the project again from its current source'), and distinguishes it from a fresh deploy by noting the address does not change. It is immediately clear what the tool does and how it differs from a generic deploy.

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

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

The description gives explicit when-to-use guidance: after fixing something in the repository or retrying a failed build. It does not explicitly name alternatives like deploy or update_site, but the context makes the intended use clear. A small deduction for not explicitly contrasting with sibling tools.

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

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

Beyond the annotations, the description discloses merge semantics (unspecified variables are kept), deletion via empty value, the fact that a redeploy is triggered, and that values are never returned. These are exactly the behavioral details an agent needs and they align with the destructiveHint and idempotentHint annotations.

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

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

Three short sentences, with the core operation front-loaded and each sentence adding a distinct piece of information: action, preservation/deletion semantics, and response shape. No filler or repetition of schema boilerplate.

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

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

For a two-parameter tool with annotations and no output schema, the description covers the action, side effects, merge/delete semantics, and response shape. The only minor gap is that it does not explicitly state whether the redeploy is automatic or a separate required step, which could affect how an agent sequences calls.

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

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

The schema already covers both parameters at 100%, including the empty-value removal behavior. The description adds important extra meaning by stating that omitted variables are preserved, which is not in the schema, and by clarifying the return contract (names only, not 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?

The description opens with a specific verb and resource: 'Set or remove environment variables on a project,' and clarifies the redeploy side effect. This makes the tool's purpose unambiguous and distinct from sibling tools like deploy or update_site, even without naming them.

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

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

The use case is implied by the action ('Set or remove environment variables'), but the description does not explicitly say when to prefer this over siblings such as deploy, redeploy, or update_site, nor does it state when not to use it. There is no direct alternative guidance, so it falls at the implied-usage level.

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

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

Annotations already mark destructiveHint=true, and the description adds specificity: 'Files missing from the folder are removed from the site,' clarifying the destructive scope. It also discloses that the address remains unchanged and no new project is created, which are non-obvious side effects beyond what annotations convey.

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

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

The description is a compact paragraph where each sentence earns its place: the core action, the key distinction from deploy, the quota effect, and the destructive behavior. It is front-loaded with the primary purpose and avoids redundancy.

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

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

Despite having no output schema, the description covers the tool's purpose, usage context, side effects, and parameter defaults. An agent has all necessary information to decide when to call it and what to expect, given the tool's simplicity and the richness of annotations.

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

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

Schema coverage is 100% and both parameters are well documented in the schema itself. The description adds no new semantic details about parameters—'id' and 'directory' meanings are already in the schema. Per the rubric, with high schema coverage the baseline is 3, and no extra value is provided here.

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

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

The description opens with a specific verb and resource: 'Replace the content of a project you already deployed and build the new version.' It immediately distinguishes from siblings by stating 'Prefer it over calling deploy again whenever you are changing an existing site,' making the tool's niche 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?

Explicitly states when to use it ('whenever you are changing an existing site') and provides a clear alternative to avoid (deploy). It also notes that it doesn't consume a quota slot, which is useful for resource planning. No ambiguity remains about when this tool is appropriate.

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