spawnpoint

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

The description adds substantial context beyond the annotations: paid-plan prerequisite, exact DNS records returned, the need to relay them to the user, verification gating, automatic HTTPS on first visit, and the fact that the share URL continues to work. These are operational details an agent needs but cannot infer from readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=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 the action and prerequisite, then moves through the DNS output, verification step, HTTPS behavior, and share URL continuity. Every sentence contributes necessary operational guidance without repetition.

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

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

Although an output schema exists, the description still explains the key return values (ownership TXT and routing CNAME/A records) and the verification lifecycle. Combined with the paid-plan caveat, verbatim relay instruction, HTTPS behavior, and share URL continuity, it is complete for this mutation 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?

The schema fully documents both required parameters, including the domain format and project_id meaning. The description reinforces the domain example and ownership requirement but does not add meaningful parameter semantics 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?

The description states a specific verb and resource: attach a user-owned domain to a spawnpoint project. It gives a concrete example and distinguishes the operation from verification and removal by naming the next lifecycle step.

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

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

It explicitly says this requires a paid plan, that DNS records must be relayed verbatim, and that verify_custom_domain should be called once those records exist. This gives clear when-to-use and next-step guidance rather than leaving the workflow implicit.

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

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

The description claims 'Idempotent: calling it again returns the same database', but the annotations declare idempotentHint=false, a direct contradiction of the declared safety/retry profile. This is otherwise a rich disclosure (app restart, DATABASE_URL persisted across redeploys, DB dropped on terminate), but the explicit conflict with structured annotations is exactly the case the rubric scores at 1.

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, then side effects, idempotency, alternatives, refusal condition, and lifecycle in that order. Every sentence carries distinct operational information; there is no filler or restatement of the name.

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

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

For a one-param provisioning tool with an output schema, it covers side effects, persistence, prerequisites, and teardown behavior. The only shortfall is that the lifecycle claim (dropped on terminate) and the idempotency claim are not reconciled with the annotations, leaving an agent unsure whether a retry has additional effects.

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, project_id, already documented in the schema at 100% coverage. The description only implies which project is targeted ('a spawnpoint project') and adds no format, constraints, or examples beyond the schema, so the baseline 3 applies.

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

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

Opens with a specific verb+resource ('Give a spawnpoint project its own Postgres database') and immediately scopes what is provisioned and where ('created on spawnpoint's managed server'). It is clearly distinguishable from siblings like add_storage or create_upload because it names the storage type (Postgres) 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?

Explicitly states when to use it ('when the app needs real relational storage that outlives its machine') and when not to ('for a SQLite file or uploads, the persistent data directory (SPAWNPOINT_DATA_DIR) needs no call at all'). It also names a blocking prerequisite ('Refused if the user already set a DATABASE_URL of their own'), leaving nothing to inference.

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

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

The description directly contradicts the idempotentHint=false annotation by saying 'Idempotent: calling it again returns the same bucket and changes nothing.' That is a serious annotation contradiction for an agent deciding whether retries are safe. Other behavioral details are rich, but the contradiction dominates this dimension.

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

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

The description is long, but it is front-loaded with the core purpose and then organized around prerequisites, runtime behavior, public/private semantics, limits, and lifecycle. Most detail is justified for a complex storage-provisioning tool, though some implementation narrative is verbose.

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

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

It covers prerequisites, env vars, server requirement, public/private behavior, plan caps, refusal cases, and termination cleanup, so it is broadly complete for this complex operation. The incorrect idempotency claim prevents a top score because it could mislead agent behavior.

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 both project_id and public well. The description adds operational guidance around public/private consequences, but it does not add much parameter semantics 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?

The description states a specific verb and resource: give a project an S3 bucket for user-uploaded/downloaded files. It also distinguishes the bucket from the persistent data directory and names related tools like deploy_project, get_project, and set_storage_visibility.

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

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

It gives explicit timing (after the first deploy_project), prerequisites (server runtime node or python), exclusions (static page cannot do this), and alternatives (SPAWNPOINT_DATA_DIR needs no call). It also clearly states when to use public versus private storage and how visibility changes later.

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

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

Annotations only declare it as a non-readonly, non-destructive, non-idempotent write; the description adds the operational traits that matter: the URL works exactly once, expires in 30 minutes, caps at three open uploads per account, and stays usable after a deploy_project rejected before it starts. Size limits (20 MiB / 50 MiB) and required exclusions (node_modules, .git) are behavioral constraints found nowhere in the structured fields. Consistent with 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?

Front-loaded with purpose and usage, and nearly every clause carries actionable information (expiry, slot limit, size caps, exclusions) with little filler. It is a single very long, heavily nested sentence-paragraph, which costs some scannability for an agent parsing constraints.

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

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

An output schema exists so return values need not be described, and the description still covers the full workflow end-to-end: how to execute the upload, what to pass to deploy_project, lifetime and slot constraints, failure recovery, and bundle limits. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is no per-parameter semantics to explain and the baseline is 4. The description does add value about the data handoff (run the returned command with bash, then pass the returned upload_id into deploy_project), but that concerns the output/next step rather than input parameters.

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 ('Send an app that is on disk to spawnpoint') and immediately frames it as a supporting step for deploy_project, making the boundary between the two tools unambiguous. The agent knows exactly what this produces (an upload URL/upload_id) and why it exists.

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

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

Explicitly names the conditions that select this path over deploy_project's inline files: files exist on disk, more than a few small text files, include images, or exceed the 4 MiB inline cap. It also gives a reuse rule (prefer an existing URL over minting a new one) and the three-slot ceiling, so both when-to-use and when-not-to-use are covered.

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

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

Annotations say openWorldHint=true, idempotentHint=false, destructiveHint=false, but the description contributes substantial extra context: the 4 MiB inline cap, refusal conditions (neither files nor upload_id, hardcoded credentials, .env/.git dropped), the url vs machine_url distinction, data-dir persistence vs app-dir replacement, and sleeping/plan limits. Far beyond what structured fields 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 purpose, but it becomes a very long dense block that mixes redeploy behavior, plan limits, data-dir semantics, and inference into one run-on paragraph. Nearly every sentence carries information, but structure suffers and some pruning would improve scanability.

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 11-parameter, nested-schema, high-stakes mutation tool with an output schema, the description covers prerequisites, failure modes, persistence semantics, secrecy rules, and next steps (call watch_deploy, give url). Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents all 11 parameters and baseline is 3. The description adds selection guidance beyond the schema, notably how to choose runtime (static vs node vs python vs docker based on server needs) and the secrets-in-env rule, which meaningfully aids correct parameter filling.

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

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

The opening states a specific verb and resource ('Put a web app, site, or page online, or update one, and get its public URL'), and immediately names the alternatives it is not (create_upload, watch_deploy). An agent can tell exactly what this does vs. its many siblings.

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

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

Explicit when-to-use ('whenever the user asks to put something online, publish it, host it, or get a link'), when-not (unless they name another place), fast-path alternatives (create_upload for on-disk apps), runtime selection rules, redeploy-by-name behavior, and plan-limit handling. This is a thorough routing guide.

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, non-destructive), and the description adds real value beyond them: the status vocabulary, that failed deploys carry error_explained and retryable, and that the url survives redeploys unless the address changes. It stops short of describing the overall response shape, but the output schema carries that.

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

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

Front-loaded with purpose, then the watch_deploy preference, then output caveats, so the most important routing information appears first. Five dense sentences, all informative, though the url/machine_url guidance could be tightened slightly.

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

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

An output schema exists so return values need no full explanation, yet the description still flags the fields an agent must act on (url vs machine_url, error_explained, retryable) and the latency expectations. Nothing needed to call it correctly or 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% and the single project_id parameter is fully documented there, so the description only restates 'by project_id' without adding format or sourcing guidance. Baseline 3 is appropriate when the schema does the work.

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), a specific resource (one project), the key (project_id), and enumerates what comes back: status values, url, health, host machine. An agent can distinguish it from list_projects (one vs many), get_project_logs (status vs logs), and watch_deploy (poll vs wait) 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 routes between siblings: after deploy_project prefer watch_deploy, and poll this only if watch_deploy is unavailable, with expected latency (1-3 min, up to ~12). It also gives output-handling rules: give the user the url, never hand out machine_url.

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

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

Goes well past the annotations: discloses runtime latency ('takes a few seconds'), a hard availability constraint (machine must exist), and concrete rate limits (burst of 10, then one every 6 seconds) with mitigation advice. This also coherently explains the idempotentHint=false annotation, since runtime logs are fetched live.

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

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

Front-loads the capability, then splits into push and runtime paragraphs, then closes with the action to take. Dense but every sentence carries operational information; 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?

An output schema exists so return shape needn't be described. The description covers the things the schema can't: which kind to try first, why a log is empty/unavailable, latency, and rate limits. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds real meaning: push is 'the last deploy's combined output: upload, dependency install, and start' and is the default, while runtime is 'the last 200 lines of the app's own journal live from the machine'. That is substantially more than the schema text conveys.

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 (fetch) and resource (a spawnpoint project's logs) plus the intent (diagnose a failed deploy or misbehaving app). It then separates the two modes of the tool (kind=push vs kind=runtime, including the default) so the agent knows exactly what each call yields.

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 ordering guidance — 'Read it first when a deploy errors' — plus a conditional on runtime ('works only while the machine exists') and an anti-polling instruction ('read it once per fix rather than polling'). The only gap is that it never names the sibling watch_deploy as an alternative for live deploy monitoring.

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

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

Goes well past the annotations (which already say readOnly, non-destructive, closed-world) by disclosing counting semantics ('activity is counted at most once a minute, so this is sessions-ish, not page views'), the meaning of a missing first_opened, the domain-row/`via` row structure, and the public-project coverage gap. These are exactly the behavioral traits an agent cannot get from structured fields and would otherwise misreport.

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

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

The core ('who opened it, when, how many') is front-loaded, and most sentences carry real semantic payload. It is delivered as one dense run-on block with several parenthetical asides, so a slightly more segmented structure would improve scannability, but there is little 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?

Even though an output schema exists, the description adds the interpretive layer needed to read it correctly (sessions-ish counting, domain rows, unopened invites). Combined with the stated coverage limits, an agent has everything needed to call it and to caveat the results appropriately.

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

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

A single required parameter with 100% schema description coverage ('the id of the project to fetch'), so the schema already does the work. The description adds no syntax, format, or lookup guidance for project_id, which is acceptable but not a value-add — 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?

Opens with a specific verb and resource: 'Report who has opened a spawnpoint project, per invited email', then enumerates exactly what is returned (opened status, first/last RFC3339 timestamps, visit count). It never names a sibling, so the distinction from get_project_logs or get_project has to be inferred from the analytics framing rather than stated.

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 decision context: 'for a restricted project this is the complete answer to "did they look at it"', which tells the agent when this tool is the right call. It also states the exclusion (a public project's anonymous traffic is not collected), though it does so as a data limitation rather than an explicit 'use X instead' routing rule.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that the fetch returns SKILL.md plus every file it uses and that SKILL.md should be followed, but says nothing about auth scope, size limits, or failure modes, which keeps it at a middling level.

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 fetch purpose is front-loaded, but the final sentence is repetitive and convoluted, restating the 'spawnpoint skill' exclusion three times across clauses before reaching the actionable fallback. It is not bloated in size yet wastes words through redundancy.

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

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

An output schema exists, so return values need not be explained, and the single parameter is documented. The description covers scope, the returned files, and the confusing edge case of unlisted skills, leaving little an agent needs that is missing.

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

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

With one parameter at 100% schema coverage, the schema already documents the 'name' argument. The description only echoes this ('by name', 'as the instructions list it') without adding syntax or formatting detail, so the baseline of 3 applies.

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

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

The opening states a specific verb and resource ('Fetch one of the team's skills by name') and even names the payload ('its SKILL.md and every file it uses'). It is clear what the tool does, though it never explicitly contrasts itself with plausible siblings like get_project or read_team_space.

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 supplies a real conditional: only skills the instructions list are 'spawnpoint' skills, and a user-only session lists none, so an unlisted named skill should be sought among the agent's own skills. That is meaningful when-not-to-use guidance, though it names no sibling 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?

Annotations already establish the read-only, non-destructive nature, but the description adds important context beyond them: url survives redeploys unless the app address changes, works for public or restricted projects, and machine_url must never be exposed because restricted projects refuse viewers there. This is valuable safety and output-handling guidance.

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

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

The description is four focused sentences: it front-loads what is listed, then states the primary use, then gives safe output guidance. Every sentence adds distinct value without waste.

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 zero input parameters and an output schema already present, the description supplies what is needed: list scope, key returned fields, usage for project_id lookup, and explicit url/machine_url safety guidance. Nothing essential for correct invocation is missing.

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

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

The tool has zero parameters and the input schema is empty, so there is no parameter behavior for the description to supplement. The baseline for zero-parameter tools 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 uses a specific verb and resource ("List the caller's spawnpoint projects") and enumerates the returned fields, including the project_id. It also distinguishes the tool's core retrieval purpose by saying it is used to find a project_id for a named project.

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

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

It gives clear usage context: find the project_id of a project the user names, and show the user the shareable url. It does not explicitly compare against alternatives such as get_project or list_team_space, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the signed-in-team precondition and the shape of the result, but says nothing about ordering, pagination, or behavior on an empty/unauthorized team space.

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 and return fields first, then the precondition, then the pointer to the read-one sibling. No filler or repetition.

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

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

With an output schema present, the description need not document return values in detail, and annotations cover the safety profile. The remaining agent-relevant facts — the session prerequisite and the sibling handoff — are both stated.

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 4 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?

States a specific verb and resource ('List the files in the team space') and enumerates exactly what is returned (name, size, who added it, when). It also ties itself to the sibling that creates these files (upload_to_team_space), so an agent can place it in the workflow immediately.

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

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

Gives the routing condition ('Read one with read_team_space') plus a hard prerequisite ('Only for a session signed in for a team'), covering when to use it, when it is inapplicable, and which sibling to use instead for a single file.

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

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

Adds substantial context beyond the annotations: same-name publishing replaces the skill with the next version (consistent with idempotentHint=false, destructiveHint=false), and replacement is restricted to the original publisher or a team admin. Neither the versioning semantics nor the authorization rule is derivable from the structured fields.

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

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

Four sentences, front-loaded with capability then constraints, and essentially no filler. Slightly dense with stacked clauses ('a folder with a SKILL.md, whose front matter has a name and a description saying when to use it'), but each sentence carries a distinct fact.

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

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

An output schema exists, so return values need not be described. The description still covers the mutation's consequences, authorization, team-session precondition, required SKILL.md structure, and both input modes – everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'files' is required unless upload_id is set, SKILL.md must be among the files, and the deploy_project analogy frames both modes. It stops short of explaining path/encoding details, which the schema already handles.

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

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

Opens with a specific verb+resource ('Save a skill for the whole team') and immediately defines what a skill is (a folder with SKILL.md plus its front matter and supporting files). It is clearly distinguished from the sibling get_skill, which is named as the consumer side, so an agent knows this is the write half of the pair.

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 prerequisite and exclusion ('Only for a session signed in for a team'), tells the agent which sibling to use for retrieval (get_skill), and routes the upload path through create_upload. It also specifies the two mutually exclusive input modes so the agent knows which 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 only cover the safety profile (readOnly, non-destructive, not idempotent). The description adds non-obvious operational traits: a 64 KiB text cap, a link that expires after 15 minutes, and the team-session auth requirement. These are exactly the behaviors an agent cannot infer from structured fields.

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

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

Three tight sentences, front-loaded with the action, followed by the return characteristics and then the access constraint. 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?

An output schema exists, so return values need not be detailed, yet the description still summarizes the payload and its limits. Size cap, link lifetime, name sourcing, and auth precondition together cover everything needed to call this correctly.

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

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

Schema coverage is 100% and there is only one parameter, so the schema already carries the syntax. The description still adds value by naming list_team_space as the authoritative source of valid names, which is more than the schema's own phrasing conveys.

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 a precisely scoped resource (one file from the team space), plus the identifying key (its name). It is clearly separable from list_team_space, upload_to_team_space, and the project-oriented siblings without opening any schema.

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

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

Explicitly routes the agent to list_team_space to obtain valid names and states a hard precondition ('Only for a session signed in for a team'). It does not spell out when a team-space read is preferable to, say, get_project, but the context is clear enough to select 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 real behavioral context beyond the annotations: the domain 'stops serving on the next request' (timing/eventual effect) and 'its certificate stops renewing', plus a clear statement that the share URL is unaffected. It does not contradict destructiveHint=true or idempotentHint=false, and it usefully narrows the blast radius of a destructive operation.

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

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

Two tight sentences with zero waste; the core action is front-loaded and the effect/non-effect clauses are packed into the second 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 an output schema present, the description needn't document return values, and it covers the salient side effects of a destructive operation. Minor omissions (whether the domain can be re-attached, any preconditions) keep it from a 5.

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

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

Schema description coverage is 100% with only two top-level parameters, so the schema already documents both fields fully. The description adds nothing about parameter format or constraints, which is the expected baseline here (though the schema's own 'hostname to attach' wording is a mild wart it does not correct).

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

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

States a specific verb (detach) and resource (custom domain) scoped to 'a spawnpoint project', so the operation is unambiguous. It does not explicitly name the sibling it inverts (add_custom_domain) or distinguish itself from verify_custom_domain, so it falls short of full sibling differentiation.

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

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

Usage is implied by the verb rather than stated: there is no when-to-use, no prerequisites (e.g., must the domain be verified first?), and no note about re-adding via add_custom_domain. Adequate for a straightforward detach operation but no explicit 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 declare destructiveHint=true and non-idempotent, but the description adds the details annotations cannot express: data is permanently unrecoverable, calling without confirm refuses and does nothing, and the app restarts without the variable. This is exactly the behavioral context needed for an irreversible operation.

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

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

Four short sentences, front-loaded with the destructive action and its effect, then the confirmation protocol, then the alternative. No redundant restatement of the schema.

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

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

With an output schema present, return values need no explanation; the description covers irreversibility, the confirmation gate, the refusal path, and the downstream effect on the app's environment. Nothing 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 100% and the confirm parameter is already documented, so the baseline is 3. The description still adds behavioral meaning by explaining the consequence of omitting confirm (the call refuses and nothing happens), which the schema does not state.

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 ("Drop a project's managed Postgres database") plus the accompanying state change ("unset DATABASE_URL"). It also contrasts with the closest sibling, rotate_database_password, so the agent can distinguish the two without opening either schema.

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

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

Gives an explicit protocol: first reply that data is deleted and unrecoverable, ask for confirmation, stop, and only call with confirm: true after a yes. It also names the alternative for a different intent (replace a leaked DATABASE_URL → rotate_database_password), leaving nothing to inference.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: it discloses that the call refuses without confirm and 'nothing happens', that the access key is deleted, that S3_* variables are unset, and that the app restarts before the bucket is removed. This is exactly the extra behavioral context an agent needs for an irreversible operation.

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

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

Front-loaded with the destructive scope, then the confirmation protocol, then side effects, then the alternative. Every sentence carries information, though the confirm-gate wording slightly duplicates the schema's own description of that parameter.

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

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

With an output schema present, return values need no explanation, and the description still covers the mutation's blast radius, side effects, restart ordering, and failure mode. Nothing 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 100% and the confirm parameter is already fully documented in the schema, including the 'ask first, and stop' nuance. The description reinforces the confirm gate but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a project's S3 bucket') and immediately scopes it ('with every file in it, for good'), so an agent knows exactly what is destroyed. It also names the sibling it is not (rotate_storage_key), which differentiates it from the add_storage/remove_storage family 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 an explicit when-to-use protocol: reply that files are gone, ask for confirmation, stop, then call with confirm: true only after a yes. It also names the alternative route for a leaked key (rotate_storage_key). Both the condition and the exclusion are 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?

Goes well beyond the annotations by disclosing the exact sequence: new password set and checked, app restarted with the new URL, and only then the old password locked and its connections ended. It also explains the no-confirmation rationale, that data is untouched, and the deploy-in-progress behaviour ('status rotating', old password valid until the deploy finishes).

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 action and its trigger are front-loaded, and each sentence carries distinct information (safety, sequencing, data preservation, deploy edge case). It runs long for a single-parameter tool, but nothing is redundant filler.

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

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

An output schema exists, and the description nonetheless covers safety, side effects, ordering guarantees, and the concurrent-deploy case. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and there is only one parameter, so the baseline is already high; the description adds the meaningful constraint that the caller should pass only project_id, confirming additional properties are not accepted.

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 ('Replace a project's managed database password') and scopes it to a single project. It is clearly distinguishable from the sibling rotate_storage_key by naming the database password and DATABASE_URL explicitly.

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

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

Gives a concrete trigger condition ('use it at once when DATABASE_URL may have leaked (printed, logged, pasted, or committed)') and an explicit calling constraint ('Pass only project_id'). It stops short of naming when NOT to rotate or pointing to a sibling alternative, which keeps it off a 5.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it discloses the exact safe rotation sequence, that the bucket and files are untouched, that presigned URLs signed with the old key stop working, and the deploy-in-progress behavior where handover occurs only when the deploy finishes (status rotating). That is precisely the operational context an agent needs before invoking a credential rotation.

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

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

Front-loaded with purpose and the leak scenario, then the safety sequence. Every sentence carries distinct information, though the sequence, presigned-URL, and deploy paragraphs could be tightened slightly for a five-sentence description.

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

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

An output schema exists, so return values need not be described, and the description still covers async status ('rotating'), downtime guarantees, and side effects. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the single project_id parameter is already documented, so the schema carries the burden. The description only adds the constraint 'Pass only project_id', which restates what additionalProperties=false already enforces and adds no new semantic detail.

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

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

States a specific verb+resource ('Replace a project's bucket access key') and the exact scenario that motivates it. It is clearly distinguishable from siblings such as add_storage, remove_storage, and set_storage_visibility, which touch the bucket rather than its credentials.

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 trigger: 'use it at once when the key may have leaked (printed, logged, pasted, or committed)'. It does not name an alternative tool or state a when-not-to-use condition, but the leak scenario plus the 'needs no confirmation' note makes the intended context 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 flag destructive=true, but the description goes well beyond them: the sweep cadence (about once a minute), the consequence that billing stops, the machine is destroyed, and that redeploying restores the same share URL. It also clarifies that passing a value sets or moves the teardown and omitting cancels it.

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

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

Front-loaded with the core action and the parameter behavior, then layers the sweep timing, semantics, and use case. Three sentences, each carrying weight, 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?

With annotations covering the safety profile, an output schema covering returns, and full schema coverage of both parameters, the description fills the remaining gaps (timing precision, irreversibility/redeploy behavior, cancellation). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% -- both the duration format/min/max and the project_id are already documented in the schema. The description's restatement of '45m, 2h, 1d' and the omit-to-cancel behavior mirrors rather than extends the schema, so the baseline 3 applies.

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

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

States a specific verb (schedule) applied to a specific resource (a spawnpoint project's teardown), and the automatic-terminate semantics cleanly distinguish it from an immediate terminate. An agent can tell what this does without opening the schema.

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

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

Explicitly frames the use case ('Right for demos, reviews, and anything that should not bill overnight') and explains the omit-to-cancel branch, giving clear context. It stops short of naming terminate_project as the immediate alternative for when scheduling isn't wanted.

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

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

Beyond the annotations (which only assert it is a non-destructive, non-readonly mutation), the description explains the sleep model, the ~30 second cold-start penalty, plan-based quotas, and the refusal contract (names the apps that are on, ask the user which to turn off). That is rich behavioral context an agent cannot get from structured fields.

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

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

Front-loaded with the core action and the sleep-vs-always-on tradeoff, then the quota and refusal handling. Every sentence carries information, though the cold-start explanation and the whoami cross-reference make it denser than strictly necessary for a two-parameter toggle.

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

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

An output schema exists, so return values need no explanation here. The description still supplies the non-obvious operational context (quota enforcement, refusal semantics, static-site exemption, whoami for limit checks), leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% and the always_on schema text already states 'true keeps the app awake... false lets it sleep'. The description restates that meaning in experiential terms (nobody waits) but adds no syntax, default, or format detail beyond the schema, so the baseline 3 applies.

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

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

The opening sentence names a specific verb (keep awake / let sleep) and resource (a spawnpoint app), and the mechanic it governs. It is unmistakably distinct from siblings like deploy_project or terminate_project, and an agent can tell what state it changes without opening the schema.

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

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

It gives explicit when-to-use ('when the user wants an app to stay up, or says it is slow to open after a quiet spell') and a clear when-not ('a static site never sleeps and needs none'). It also covers the limit case, directing the agent to turn apps off rather than blindly retrying.

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 flag destructiveHint and openWorldHint, but the description goes well beyond them: it discloses the 30-day forwarding window, that the old name becomes claimable by anyone afterward, that email verifiers must re-verify, and that invalid names are refused with a reason. These are exactly the side effects an agent needs before committing a rename.

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?

Information is front-loaded with the core action and format first, then consequences, then the caution. It is dense with five sentences, and the email re-verification note is somewhat peripheral, but every sentence contributes behavioral or constraint value rather than filler.

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

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

An output schema exists, so return values need not be explained; the description instead covers the irreversible consequences, the format contract, and the pre-call confirmation rule. For a destructive, non-idempotent rename with just two required parameters, nothing an agent needs 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 formatting basics are already present, yet the description adds real constraints the schema omits: lowercase-only, digits and hyphens, and a 3-to-40 character length bound. This meaningfully reduces malformed calls beyond the schema's example-only guidance.

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 the address a spawnpoint project is reached at') and immediately disambiguates the concept with 'the part before .spwt.app, e.g. lunch-orders'. This clearly separates it from siblings like share_project and add_custom_domain without requiring schema inspection.

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

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

Gives a concrete when-to-consult-the-user rule ('Ask before renaming an app the user did not just make') and ties it to the consequence of already-sent links forwarding. It also advises keeping apps restricted when the address is guessable. It does not name sibling alternatives explicitly, so it falls short of a 5.

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

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

Annotations already declare this is a mutating, open-world, non-idempotent write; the description adds substantial context beyond them: it restarts the app, sets/unsets S3_PUBLIC_URL, exposes files with no gate or app request, keeps the file list private, and surfaces a warning to relay for restricted projects. This is exactly the extra behavioral detail annotations cannot carry.

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

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

Front-loads the action, then contrasts public vs private, then appends operational side effects (restart, warning). The middle public/private contrast is slightly repetitive with the schema, but every sentence carries distinct information and nothing is padding.

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

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

With an output schema present, the description need not explain return values, and it fully covers the mutable behavior, side effects, and the safety-relevant warning. Nothing an agent needs in order to invoke this correctly is missing.

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

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

Schema description coverage is already 100% and the 'public' property description nearly duplicates the prose in the main description. The added value is marginal, though the surrounding context ('files bypass the gate', 'restricted project warning') does clarify consequences of the flag beyond the schema's literal text.

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

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

States a specific verb+resource ('set storage visibility') and immediately scopes it to a spawnpoint project's bucket, tying it to the add_storage resource created by a sibling. An agent can distinguish it from set_visibility, add_storage, and remove_storage without opening any schema.

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

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

Gives explicit when-to-use guidance for the value choice ('right for a public gallery, wrong for user documents'), which is the key decision. It does not, however, name or exclude sibling tools the agent might reach for instead (e.g. set_visibility vs this), so routing is implied 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?

Beyond the annotations (readOnly=false, destructive=false), it discloses that effect is immediate at the URL, that machine reconfiguration happens in the background within seconds, that a sleeping project is woken, that an in-progress deploy picks the change up on completion, that same-value calls are no-ops, and that the share URL is stable. It also flags a side effect an agent must relay: a warning when a restricted project has a public bucket.

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

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

The core operation is front-loaded in the first clause and every subsequent sentence carries real behavioral information. The parenthetical-heavy run-on styling (three nested asides in one sentence) slightly hurts scannability and could be split for faster parsing.

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

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

With an output schema and annotations already covering safety and return shape, the description fills the remaining gaps an agent needs: timing, edge cases (sleeping project, in-flight deploy, no-op), URL stability, and the bucket/app scope boundary. Nothing material is left unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what 'restricted' operationally means (owner plus shared emails, verified by a one-time code) rather than merely restating the enum. project_id receives no extra treatment, but nothing is ambiguous.

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 ('flip a spawnpoint project between restricted ... and public') and immediately defines both states, so an agent knows exactly what changes. It is distinguishable from set_storage_visibility/add_storage because it explicitly scopes the gate to the app rather than a bucket.

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: call this to change app access at the share URL, and the description contrasts the app gate with a public bucket. However, it never names the sibling tools an agent might confuse it with (share_project, unshare_project, set_storage_visibility, set_share_slug) or states when not to use it, so routing still requires 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 cover non-destructive, open-world, write behavior, but the description adds substantial context beyond them: invite-email + one-time-code verification with no account, no email sent in domain mode, immediate effect, and allow-list scope relative to project restriction. One nuance keeps it from a 5: the claim that re-adding an existing entry is harmless and sends no second email reads as idempotency, which sits awkwardly with idempotentHint=false, though the safety-relevant hints (write, open-world, non-destructive) all agree.

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

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

The purpose and primary mode are front-loaded, and each subsequent sentence carries real content (domain mode, consumer-domain exclusion, immediate effect, idempotent re-add, allow-list scope). It is dense - six sentences - but earns most of its length given the tool's two-mode 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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. Everything an agent needs to choose the right mode, avoid consumer domains, and know the side effects (email, immediate effect, no account needed) is 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 description coverage is 100%, so both parameters are already documented, including the @company.com domain form for email. The narrative adds the rationale (consumer-domain refusal, added-to-allow-list effect) but no syntax or formatting detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb (share) and resource (a restricted spawnpoint project) and immediately distinguishes the two modes: one person by email vs. everyone at a domain. An agent can tell exactly what this does and how it differs from related tools such as set_visibility or unshare_project 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 explicit when-to-use for each mode (single email vs. @company.com), an explicit when-not (consumer domains like @gmail.com are refused), and an alternative action ("make the project public instead"). It also states the precondition that the allow list only matters while the project is restricted.

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 substance beyond that: irreversible data loss across five distinct resource types, billing termination, the fact that an unconfirmed call refuses and changes nothing, and that a later redeploy reclaims the URL but not the data. That last point is a non-obvious side effect an agent could not infer.

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 destruction inventory, then the confirmation protocol, then the alternative — a sound ordering with no filler. The opening sentence is long and clause-heavy, which strains readability for such a high-stakes tool, but every clause 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?

A destructive, irreversible, confirmation-gated operation with an output schema; the description covers blast radius, gating behavior, billing effect, post-deletion URL reuse, and the deferred-teardown alternative. Nothing an agent needs before invoking 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 the baseline would be 3, but the description adds the conversational contract for confirm — it must follow an explicit user 'yes' about named losses, and a delete request is not itself that yes — plus the runtime consequence that omitting it causes a no-op refusal. project_id gets no added meaning beyond the schema, which keeps it off 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?

Names a specific verb and resource ('Delete a project for good') and then enumerates exactly what ceases to exist: machine, URL, app files, SQLite database, managed Postgres, and storage bucket contents. That level of specificity makes it unmistakable against siblings like remove_database or schedule_teardown.

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

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

Explicitly states the required pre-call protocol (tell the user what is lost, ask, stop, call with confirm: true only after a yes) and names the alternative for a different intent: 'To take a project down later rather than now, use schedule_teardown instead.' Both the when and the when-not are covered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real operational context the annotations cannot convey: revocation is instant because the gate re-reads the allow list live on the viewer's next request, and removing a domain does not revoke addresses shared individually. It stops short of covering idempotency or error behavior for repeat/absent entries.

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 with no filler; the core action is front-loaded and the timing and edge-case notes follow in order of importance.

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

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

An output schema exists so return values need no explanation, and the description covers action, timing, and the domain-vs-address edge case. It omits what happens when the entry was never shared (error vs. silent no-op) and whether project ownership is required, which for a destructive, non-idempotent operation would be worth one more clause.

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

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

Schema description coverage is 100%, and the schema for 'email' already spells out the address-or-domain form, so the description adds little there. Its only extra value is behavioral (domain removal leaves individually shared addresses intact), which is not a parameter-syntax clarification, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Remove one email, or one domain ... from a spawnpoint project's allow list.' The scope (single entry vs. domain) is explicit, and the inverse relationship with share_project is unmistakable without opening either schema.

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

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

The description clarifies what a call accomplishes but never states when to prefer it over alternatives or names the sibling tool (share_project) that performs the opposite action. Usage is implied rather than routed.

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?

Far beyond the annotations, it discloses the signed-URL mechanics, the 30-minute expiry, that the key never leaves spawnpoint, the 50-file-per-call limit, refusal while the bucket is over its plan limit, and that uploading to an existing key replaces the file. The replacement semantics are the one point of mild tension with destructiveHint=false, but the behavior is explicitly disclosed rather than hidden.

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

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

It is a single dense paragraph with the purpose front-loaded and almost every clause carrying operational information (ordering, limits, URL semantics). It is longer than strictly necessary for a two-parameter tool and the public/private bucket readability point is stated twice, but there is little pure 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 upload tool with an output schema and full annotation coverage, the description supplies everything the agent needs: prerequisites, ordering, path semantics, limits, overwrite behavior, and how to execute the returned command. Nothing material is missing.

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

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

Schema description coverage is 100%, and the schema already explains that each path becomes the object key, the allowed characters, and the 50-file cap. The description largely restates this (relative to the folder the returned command runs from, path-as-key, public URL readability), adding context but little new parameter meaning, 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 names a specific verb and resource ('Put files from disk into a project's bucket') and immediately scopes it against the sibling add_storage by noting no server is involved. An agent can distinguish it from add_storage, create_upload, and upload_to_team_space without opening any schema.

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

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

It gives explicit prerequisites and ordering ('First deploy_project, then add_storage ... then this') plus concrete use cases (static site images, installers under the 20 MiB cap, seeding a bucket). It does not, however, distinguish itself from the sibling create_upload, so the alternative-selection guidance is incomplete rather than exhaustive.

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

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

Goes well beyond the annotations: it discloses the two-step workflow (pass relative paths, then run the returned command with bash from that folder), the signed-URL mechanism with a 30-minute expiry, the overwrite rule ('A path that exists replaces the file'), and a 50-file cap. This is exactly the operational context an agent needs.

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

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

Front-loaded with the core action and then layered with workflow, limits, and overwrite behavior. The opening clause about 'the team's context and data, such as priorities, customer lists, and briefs' is slightly promotional but brief enough to keep the description efficient.

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

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

With an output schema present, return values need not be explained; the description instead covers preconditions, execution mechanics, overwrite semantics, and quotas. Nothing material to a correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents the single files parameter. The description still adds meaning by tying paths to the folder from which the returned command runs and noting each path becomes the file's name in the space, which is useful framing 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+resource (put files from disk into the team space) and defines what the team space is, including its shared-read purpose. An agent can distinguish it from sibling upload_to_storage and create_upload without opening either schema.

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

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

Gives an explicit precondition ('Only for a session signed in for a team (whoami shows team)') that tells the agent when the tool is valid. It does not, however, name or compare against the sibling alternatives (upload_to_storage, create_upload), so routing 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false), the description discloses the side effect (success means the domain serves the project with automatic HTTPS), the non-terminal failure state (result stays pending), and what a pending result carries (expected records plus a plain-language reason). That tells the agent this is an external-DNS-dependent, re-runnable mutation whose failure is informational rather than an error.

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

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

Three sentences, front-loaded with the action, then the sequencing constraint, then the failure/retry contract. No restatement of the title, no filler, and each sentence supplies information the agent needs to avoid a wrong call or a premature error report.

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

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

The tool has 2 required params, full schema coverage, and an output schema, so return shape needn't be explained — yet the description still characterizes the pending payload at a high level. For a low-parameter, externally-dependent verification tool, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% for both parameters, including the hostname format constraint, so the schema already carries the semantics. The description adds only the implicit constraint that the domain must already be claimed, which is contextual rather than parameter-level guidance. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Re-run the DNS check for a claimed custom domain") and positions itself relative to the sibling add_custom_domain, which it names as the prerequisite. An agent can distinguish this from add_custom_domain / remove_custom_domain without opening any schema.

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

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

Explicit sequencing ("add_custom_domain first"), explicit expected-failure condition ("Failure is normal while DNS propagates"), and explicit retry guidance ("wait a few minutes and call again"). It tells the agent both when to call and how to interpret a negative result, which is exactly the ambiguity that causes retry loops.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, yet the description adds substantial context: progress notifications are streamed per step and should be relayed, a static site settles immediately with nothing booting, and wait_seconds exhaustion returns 'spawning' rather than an error. It also clarifies that a harness-side cutoff (jcode's 30s) is not a deploy failure, which is exactly the kind of behavioral nuance 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?

Front-loaded with purpose and primary outcomes, then layered with recovery loop, timeout handling, and the url vs machine_url warning. Every sentence carries operational value, but it is a dense single block that would scan faster split into short lines or bullets.

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 statuses (running, error, spawning), the static-site shortcut, notification streaming, the wait/retry protocol, and which URL to hand the user versus never exposing machine_url. With an output schema present, return values need no further explanation, so nothing an agent needs is missing.

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

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

Schema coverage is 100% and the wait_seconds description already covers default 180, max 300 and settle-early behavior. The tool description adds genuinely new guidance beyond the schema: pass a smaller wait_seconds such as 20 when the harness truncates calls, and call again until it settles.

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 ('Wait for a deploy to finish') and pins its position in the workflow ('call it right after deploy_project, with the project_id it returned'). That framing separates it cleanly from siblings like get_project, get_project_logs and deploy_project itself.

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 sequencing (right after deploy_project), explicit failure path (read error_explained and get_project_logs, fix files, redeploy under the same name), and explicit retry loop when status is spawning. It even names the sibling tools to reach for on error instead of this 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 only say readOnly/no-destroy, so the description usefully adds that results are team-scoped when signed in for a team ('the plan and counts are then the team's'), that comp plans are distinguished from paid, and that there is no balance to report. It stops short of stating that the call takes no input or that output is a fixed snapshot, and several disclosed fields duplicate the output schema.

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

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

The core purpose is front-loaded, but the opening sentence runs on through a long comma-chained inventory of return fields (email, team, role, plan, comp status, project counts, always-on limits, plugin_version, plugin_note) that the output schema already encodes. Roughly a third of the text is redundant with structured data.

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?

Because an output schema exists, the description need not define return values, yet it still supplies the interpretive context an agent needs: team-vs-personal scoping, comp vs paid, always-on counting across all covered apps, and the plugin_note comparison advice. Nothing required to call this zero-arg tool correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. It correctly implies a pure no-argument introspection call, though it never says so explicitly.

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: 'Report which spawnpoint account this session is authenticated as,' then enumerates the exact fields surfaced (email, team, role, plan, active projects, always-on apps, plugin_version). No sibling tool does identity or plan introspection, so it is trivially distinguishable from the list/deploy/storage 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?

Gives two concrete triggers ('when the user asks whose account is connected or what plan they are on') plus a proactive one ('before offering to keep an app always on'), which explicitly couples it to the set_always_on sibling. It also routes the agent away for the adjacent need: 'users manage billing in the console,' effectively a when-not.

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