Server4Agent

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

The description adds important behavior beyond the annotations: a key has one account-wide value shared across every server and project where it is bound, and passing value changes it everywhere. It also warns that a project needing its own value requires a separate key, which is exactly the kind of consequence an agent needs before invoking a destructiveHint=true tool.

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

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

The description is four tight sentences with the primary action and scoping rules front-loaded. Every sentence adds distinct, necessary information, especially the account-wide value warning.

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

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

Given full schema coverage, an output schema, and annotations covering mutation/idempotency, the description supplies the missing conceptual model: binding scope, set-versus-bind behavior, and the shared account-wide value semantics. Nothing material for correct invocation appears to be 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 is 3, but the description adds semantic context not obvious from the schema: value is not scoped to the single binding but mutates the account-wide key value everywhere it is bound. It also clarifies the server_id/project_id scoping relationship.

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+resource ('Bind a secret to a scope') and immediately explains the resulting behavior ('runs there see it as an env var'), distinguishing server-wide from project-scoped binding. It also distinguishes binding-only from set-and-bind in one call, making the tool's role clear.

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 conditions for the two invocation modes: server-wide when only server_id is supplied, project-scoped when project_id is also supplied, and set-and-bind when value is passed versus binding an existing key when omitted. It does not name sibling alternatives such as set_secret, so it stops short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the substance those hints lack: exactly what is destroyed (workspace, slug, project slot) and the failure mode for persistent projects. It stops short of stating irreversibility or recovery options, so it is strong rather than exhaustive.

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

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

Three short sentences: action and effects first, the exclusion rule last. Every clause carries information an agent needs; nothing is redundant with the title or annotations.

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

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

With an output schema present, return values need no explanation, and the single param is fully documented in the schema. The description covers the destructive scope and the sibling routing, leaving nothing an agent needs missing for correct invocation.

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

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

There is a single parameter with 100% schema coverage, and the schema already explains that project_id comes from create_project or list_projects. The description adds no format, validation, or sourcing detail beyond that, 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?

Specific verb (clean up) plus a specific resource (ephemeral project), with concrete effects enumerated: deletes the workspace, retires the slug, frees the project slot. It also names the sibling it is not (delete_project), so an agent can distinguish it 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?

States the selection condition explicitly: use this once the task is done and the project is ephemeral; persistent projects error here and should go to delete_project. Both when-to-use and when-not-to-use are covered with the named alternative.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds genuinely new context beyond that — projects going offline, billing stopping, and dependent tools returning a 'paused' response rather than waking the server. That last point is a non-obvious side effect an agent could not learn from the annotations or schema. It stops short of saying whether restart is disruptive to running builds or whether a paused server auto-resumes.

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

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

Two sentences: the first front-loads the action mapping, the second delivers the state semantics. No filler, and the most decision-relevant fact (a paused server stays down until started) is not buried.

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

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

With an output schema present and annotations covering the safety profile, the description gives enough to call this correctly, including the counterintuitive 'does not wake' behavior. A minor gap remains around restart-specific impact (e.g., in-flight builds or unsaved state) and whether permission requirements apply.

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 enum already documents start/stop/restart semantics in nearly the same words used here ('stop pauses it', 'restart reboots it'). The description restates rather than extends that 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?

States a concrete verb set (pause/stop, resume/start, reboot/restart) against a specific resource, and the parenthetical mapping to the enum values leaves no ambiguity about what the tool does. It does not explicitly distinguish itself from lifecycle siblings such as delete_server, update_server, or get_server, so the reader must infer that boundary.

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

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

The description implies usage via the consequence model (a paused server stays down until started), but never states when an agent should prefer this tool over delete_server, update_server, or when to use restart rather than a stop+start pair. The mentions of prompt, exec, start_app, file tools and start_build describe downstream effects rather than selection guidance.

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

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

Annotations already declare non-read-only, open-world, non-idempotent, non-destructive, so the description focuses on what annotations cannot express: the cap-based failure mode, secrets being write-only, template-default override precedence, and the critical operational fact that a project only serves while a process listens on `listen_port`. It does not discuss deletion/teardown reversibility beyond pointing at cleanup_project, which is a minor gap.

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

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

One dense paragraph, front-loaded with purpose and URL semantics before lifecycle/template/secrets details. Nearly every sentence carries distinct operational information, though the block is long enough that a reader must scan rather than parse quickly; splitting the `listen_port` note into its own line would help.

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

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

For a 10-parameter nested-object creation tool with an output schema, the description covers the decisions the schema cannot: seeding strategy, lifecycle/cleanup pairing, template override precedence, cap failure, and the binding requirement for `listen_port`. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns a step up by adding rules not in the schema: name is derived from the repo/archive when omitted, explicit fields override template defaults, and secrets are write-only env vars bound at creation. The access vs visibility interplay is left to the schema, which is reasonable.

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

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

States a specific verb and resource ("Create a project on a server") and immediately scopes what a project is: a home for one web page/site/app/API/bot with its own URL. It distinguishes itself from create_server and from list_templates by naming the prerequisite relationships 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 concrete when-to-use routing: lifecycle="ephemeral" for one-shot work plus "call cleanup_project after", persistent as the default for monitors/dashboards; `template` when a starter exists vs `source` for your own code. It also names the failure condition (tier project cap), so the agent knows when this call will not succeed.

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), it discloses the non-obvious operational traits: roughly one minute of asynchronous provisioning that must be awaited via get_server, secrets being write-only, and the returned server id. No contradiction with the declared hints.

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

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

Front-loaded with purpose, then workflow constraint, then parameter notes, then the provisioning delay — a sensible order. Slightly redundant with the schema on secrets and the browser kind, and the sentences are long, but no line is filler.

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

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

For a six-parameter, zero-required creation tool with an output schema, nothing an agent needs is missing: prerequisite check, side effects, write-only values, latency, and the readiness gate are all covered. Return shape is delegated to the output schema, as appropriate.

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 kind, tier, region, project_sharing, and the secrets item shape are already fully documented. The description's mentions of `secrets` (server-wide, shared by every project, write-only) and `kind: "browser"` largely restate the schema in abbreviated form, adding only the sharing scope implied by 'server-wide'. 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 ('Provision a sized server box') and immediately situates it in the object model: servers hold projects, projects get URLs. It is clearly distinguishable from create_project, get_server, and list_servers named in the text.

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

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

Gives explicit routing logic: check list_servers for a server with room before creating another, and poll get_server until provisioning reads ready before writing files. It also names the condition that selects the browser variant, so precedence between this tool and its siblings is fully determined.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the danger profile and repeat-safety are covered structurally. The description adds only the path-resolution rule and says nothing about behavior on a missing path, permission requirements, or whether deletion is recoverable, so it contributes modestly beyond annotations.

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

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

Two short sentences, front-loaded with the action, then the one non-obvious resolution rule. No filler and nothing repeated unnecessarily.

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 annotations cover destructiveness and idempotency. The path-resolution gotcha, the main source of wrong calls, is addressed; only error behavior on nonexistent files is unstated.

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

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

Schema description coverage is 100%, and the description's statement about project_id resolving path inside the project folder is essentially a restatement of the project_id and path schema descriptions. Baseline 3 applies since the schema already does the heavy lifting.

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

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

States a specific verb and resource ("Delete a file from the server's workspace") with clear scope. It does not distinguish itself from nearby siblings such as delete_project, cleanup_project, or delete_secret, so an agent must infer the boundary between deleting a file and deleting a project/secret.

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 explains path resolution but never says when to use this tool versus alternatives (e.g., cleanup_project for bulk removal, list_files to confirm existence). There are no prerequisites, no confirmation guidance, and no when-not-to-use clause.

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 and idempotentHint, so the safety profile is covered. The description adds a concrete, user-visible consequence beyond the annotations: 'The public URL stops working immediately,' which tells the agent the effect is instantaneous and externally observable. It stops short of saying whether nested resources (files, secrets, deployments) are also removed.

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

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

Two short sentences with zero filler, and the effect is front-loaded right after the action. Nothing to trim.

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

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

An output schema exists and annotations cover destructiveness, so the description only needs the essential effect, which it provides. The remaining gap is cascade scope — whether deleting a project also destroys its files, secrets, and servers — which matters for a destructive tool in a suite with many child resources.

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

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

Only one parameter and schema description coverage is 100%, with the schema already explaining where project_id comes from. The description adds no syntax, format, or constraint information beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Delete a project') that unambiguously identifies the operation. It does not distinguish itself from the sibling cleanup_project, which is the most plausible alternative an agent could confuse it with.

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

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

There is no guidance on when to use this instead of cleanup_project, no prerequisites (ownership/permissions), and no warning about when not to use it. The agent must infer everything from the name and the destructive annotation.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds information annotations cannot express — that all of the secret's bindings are destroyed alongside it — which is exactly the kind of blast-radius context an agent needs. It stops short of saying whether deletion is recoverable or what permissions are required.

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

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

One sentence, front-loaded with the verb and resource, with zero filler. The destructive scope detail is attached to the action rather than buried later.

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 annotations carry the safety profile for this single-parameter tool. The one real gap is that irreversibility and the downstream effect on anything using those bindings are not spelled out.

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

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

Schema coverage is 100% and the single parameter's description already tells the agent to obtain the id from list_secrets. The tool description adds nothing about the parameter, but with full schema coverage 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?

Specific verb+resource ('Delete a secret') with the added scope detail that bindings are removed too. It is clearly distinguishable from set_secret, attach_secret, and list_secrets, though it does not name any sibling explicitly.

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

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

There is no statement of when to use this versus alternatives (e.g., detaching a binding vs. deleting the secret), no prerequisites, and no warning about when not to call it. The only usage signal is the implied 'call this to remove a secret.'

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, so safety semantics are covered. The description's real contribution is disclosing the cascade — every project on the server is destroyed — which is not derivable from annotations or schema and is exactly the fact an agent must know before calling.

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

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

One sentence, zero waste, front-loaded with the action and immediately qualified by its blast radius. Nothing extraneous and nothing buried.

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

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

An output schema exists so return values need no explanation, and annotations carry the destructive/idempotent profile. The cascade is covered; only irreversibility/confirmation expectations and any permission requirements are left implicit.

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

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

Schema coverage is 100% with a single required server_id whose description already explains provenance (create_server or list_servers). The description adds nothing about the parameter, so baseline 3 applies.

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

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

Specific verb ("tear down") paired with a specific resource ("server"), plus the critical scope detail that all projects on the server go with it. It is clearly distinct from delete_project or cleanup_project, though it never names them 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?

States no conditions for use, no preconditions, and no alternatives. An agent must infer on its own when to prefer this over cleanup_project or delete_project, and whether confirmation or a prior get_server check is expected.

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 (openWorldHint, non-idempotent, non-destructive), it discloses the exact preflight checks (listen_port, making the project public, URL answering), the two possible statuses returned (live vs publishing), and the failure semantics (refusal with no state change). This is exactly the behavioral context annotations cannot carry.

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

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

Front-loads the verb, the resource, and the resulting URL before any caveats, and every clause carries information. It is dense and somewhat run-on with stacked colons and parentheticals, costing a bit of scannability.

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 preconditions, side effects, failure mode, and workflow ordering for a non-idempotent, open-world mutation. Even though an output schema exists, the description's status explanation reinforces what success looks like without redundant detail.

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

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

Schema coverage is 100%, so both parameters are already documented at baseline. The line 'Pass project_id; a server with exactly one project deploys that one without it' restates what the schema's project_id description already says, adding emphasis but no new semantics.

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

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

States a specific verb (deploy) and resource (a project to its live public URL), and concretely describes the outcome URL pattern. It explicitly positions itself against start_app, start_build, and prompt, so an agent can distinguish it from siblings without opening schemas.

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

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

Gives explicit when-to-use (last step in putting a site online), when-it-won't-work (nothing listening on listen_port → refuses and leaves project unchanged), and named alternatives plus ordering (start_app after write_file, or start_build/prompt). Nothing is left to inference.

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

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

Goes well beyond the destructive/openWorld annotations: execution user, sudo requirement, project secrets injected as env, session lifetime tied to the call, the ~20s output window, and the blocking side effect on other commands. These are exactly the traits an agent would otherwise learn by failing.

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

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

Dense but front-loaded: purpose, project_id behavior, intended uses, then the critical timeout and long-running caveats. The last two sentences are long and would read better as separate short rules, but nothing is filler.

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

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

An output schema exists so return values need no explanation; the description instead covers the operational facts that schema can't convey – timeouts, blocking, environment, permissions, and the correct pattern for long work.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real meaning for project_id by explaining the workspace folder, the PORT variable it sets, and the secrets it exposes. server_id and command get no extra detail, but the schema already covers them.

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 ('Run a shell command on the server and return its output') and immediately distinguishes the two modes via project_id. It also explicitly separates itself from start_app, so an agent can route correctly without opening the schema.

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

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

Names concrete intended tasks (installing dependencies, building, inspecting files) and an explicit exclusion with the alternative ('do not use it to start an app... use start_app, which keeps it running'). The when-not is paired with the reason and the sibling that handles it.

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

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

Beyond annotations, the description discloses exactly what is included and excluded from the bundle, including security-relevant behavior: dependency caches, git history, .env files, and credential files are never included. It also explains the time-limited link and portability across deployments, which are meaningful behavioral details not captured by the annotations alone.

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

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

The description is three sentences, front-loaded with the core action and return value, followed by security exclusions and the import handoff. Every sentence adds useful information 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?

An output schema exists, so the description need not explain return values in detail. It still covers inclusion/exclusion rules, security constraints, link behavior, and cross-deployment compatibility, leaving no major gap for an agent to call the tool 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 both project_id and ttl_seconds are already documented in the input schema. The description mentions a time-limited link but does not add syntax or format details beyond the schema's default and maximum ttl behavior. Baseline 3 is appropriate when the schema carries parameter semantics.

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

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

The description uses a specific verb and resource: it packages a project into a portable bundle and returns a time-limited download link. It also distinguishes the output from import_project by explaining the bundle's intended handoff, so an agent can identify the tool without opening schemas.

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

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

The description clearly states the downstream use case: hand the bundle to import_project on this or another Server4Agent deployment. It does not explicitly say when not to use export_project, but the import context strongly implies the intended workflow.

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

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

Adds genuinely useful state semantics beyond the readOnly/non-destructive annotations: a failed build still reports status 'completed' with error explaining why, and url only appears once built and public. These edge cases are exactly what an agent would otherwise misread. It does not cover auth or freshness/refresh expectations, keeping it short of a 5.

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

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

The core purpose is front-loaded, but the remaining text is a dense run-on that mixes status vocabulary, URL timing, and run linkage in one breath; 'The steps move together' is unclear on first read. Every clause carries information, yet the packing hurts 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?

An output schema exists, so return structure need not be explained, and the description still covers the non-obvious state model and the build-to-run linkage. For a two-param read tool this is sufficient, with only minor gaps like whether repeated polling is expected.

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 build_id and server_id are already fully documented as inputs, and the description adds no format or constraint detail for them. Its extra explanation is about output fields (url, run_id, status), which does not raise input-parameter clarity above the baseline.

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

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

States a specific verb and resource ('Get a build's status') and immediately frames the linked run so the agent can distinguish this from get_run, which it names explicitly. The status vocabulary (running/done/failed) further pins down what is being retrieved.

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?

Routes the agent to get_run for live progress and to prompt with follow_up_of when run_status is awaiting_input, which is real when-to-use guidance. It stops short of stating exclusions (e.g., when to prefer get_run over get_build entirely), so it is strong but not fully 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?

Adds security-critical behavior beyond annotations: the link is time-limited, requires no login, and works for anyone holding it. The explicit warning to only mint shareable files gives the agent the access-control implications that openWorldHint alone does not convey. This is exactly the contextual disclosure 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?

Three tight sentences, front-loaded with the core action, followed by the project-scoping nuance and the sharing caveat. Every sentence earns its place with no repetition 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 100% schema coverage, a non-trivial annotation set, and an output schema, the description supplies everything the agent needs: purpose, invocation context, scoping behavior, and the security implication of the returned URL. No material gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's note that path resolves inside a project's folder when project_id is given restates what the schema already documents, and it adds no new syntax or format detail for ttl_seconds or server_id.

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 ('Mint') and resource ('time-limited link to download one file from the server's workspace'), and implicitly distinguishes itself from content-reading siblings via 'hand this URL back to the user instead of the raw content'. It also gives concrete usage examples (after generating a report or converting a file).

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

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

Provides clear context for when to use ('after generating a report or converting a file') and a safety-based when-not ('only mint it for files that are OK to share'). The alternative is only implied ('instead of the raw content') rather than explicitly naming read_file, so it falls just short of a full when/when-not/alternatives rubric.

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

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

Beyond the readOnly/non-destructive annotations, it discloses that reads are live at call time, that a non-responsive server yields cached tails with stale: true and an age note, and that logs persist across restarts. This is exactly the failure-mode context an agent needs that 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-loads the core action and return shape before the caveats about staleness and usage. Dense with information and largely waste-free, though the parenthetical path detail could be trimmed.

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

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

With an output schema present, the description need not explain return values, and annotations cover the safety profile. It nonetheless covers the one thing structured fields cannot: degraded/stale behavior when the server is unavailable. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% so the field-level meaning is already documented, but the description adds purpose-level semantics for project_id (narrowing to one project's workspace logs) and clarifies the entry-per-log-file return shape. It adds modest value above the schema baseline.

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

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

States a specific verb (read) and resource (latest log tails from a server), and precisely defines the unit of return: one entry per log file written by a project's processes. The log file path convention (.server4agent/<name>.log) further concretizes what is being read, distinguishing it from generic file-reading 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 explicit use cases: debug a crashing app or check what a background process is doing, and explains the project_id narrowing behavior. It does not explicitly name alternative siblings (exec, read_file) or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: url_status is explicitly not a health check, listen_port can be null on legacy projects requiring the published 8080 fallback, and run_plan may be unsettled. These caveats prevent real misinterpretation, though error/not-found behavior is unaddressed.

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

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

The purpose is correctly front-loaded in one clean sentence, but it is followed by a dense three-part exposition on output-field semantics that reads as documentation for the return payload rather than the tool call. Every clause is factual, yet the block is long and unstructured relative to a one-parameter read.

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

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

With an output schema present, the description need not explain return values, yet it goes further and clarifies the traps in those values, which makes it more than complete on that axis. The remaining gap is failure modes and whether listing alternatives exist, which for a simple single-resource read is minor.

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

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

Schema coverage is 100% and the single project_id parameter is fully documented as coming from create_project or list_projects. The description adds nothing about the parameter itself, so baseline 3 applies with the schema doing all 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?

The first sentence states a specific verb and resource and enumerates the exact fields returned (name, slug, description, URL, listen port, run plan, timestamps). It is unambiguous about what the tool does, but it never contrasts itself with siblings like list_projects or get_run, so the agent must infer the distinction from the name alone.

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

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

Usage is only implied: the required project_id and the schema note that ids come from create_project or list_projects hint at the retrieval workflow. There is no explicit statement of when to call this versus list_projects for a batch, nor what to do when the project is missing.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: this is a polling endpoint and the response is a snapshot including workspace mutations, not just a boolean status.

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

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

Two sentences, zero filler, and the highest-value facts (what you get back, then how to poll it) are front-loaded in that order.

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-value explanation is optional; combined with 100% parameter coverage and annotations covering safety, this description leaves nothing an agent needs for correct invocation. Polling semantics are the one extra piece of intent that structured fields can't express, and they are 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?

Schema description coverage is 100%, so both parameters are already documented; baseline 3 applies. The description restates the run_id provenance but drops start_build from the list the schema gives, adding no meaning beyond the schema and introducing a minor inconsistency.

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+resource ("get a run's status") and enumerates the four payload components returned: status, latest progress note, final response, and workspace changes (commit, branch, files). It is clear enough to distinguish from get_build/get_logs by payload, though it never names those siblings explicitly, so a 4 rather than a 5.

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

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

"Poll this with the run_id returned by prompt or init_project" gives a concrete usage pattern (repeated polling) and identifies the upstream call that produces the identifier. It stops short of saying when to prefer get_build or get_logs instead, so no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description contributes interpretation help for one returned field (kind: 'standard' for headless vs 'browser' for a screen), but says nothing about error behavior, missing servers, or freshness of capacity/project counts.

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

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

Two sentences, both earning their place: the first front-loads what is retrieved, the second disambiguates an otherwise opaque field value. 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?

A read-only getter with one fully documented parameter and an output schema, so return structure needn't be re-explained. The description is sufficient to call it correctly; only usage routing against list_servers is absent.

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

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

With a single parameter at 100% schema coverage, the schema already fully documents server_id including where to obtain it (create_server or list_servers). The 'kind' explanation describes a response field rather than a parameter, so it adds no parameter-level meaning. 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 uses a specific verb ('Get') plus a resource ('a server') and enumerates the exact attributes returned (tier, kind, status, capacity, project count, project sharing), so it is clearly distinct from list_servers and get_project. It stops short of naming siblings or stating the single-server vs. list distinction explicitly, which keeps it out of the top band.

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

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

There is no when-to-use guidance, no mention of how this differs from list_servers or update_server, and no stated prerequisite such as needing a server that already exists. Usage is only inferable from the name and required server_id.

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 goes well beyond that by disclosing the failure mode (dispatch fails at the ceiling) and precisely which operations are blocked versus unaffected. That is exactly the kind of operational context annotations cannot express.

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

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

Three sentences, front-loaded with what is returned, then the when-to-call guidance, then the blast-radius detail. Every sentence carries information, though the trailing list of unaffected tools is slightly verbose relative to the core message.

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 shape needn't be re-explained, and the description still covers the operational semantics an agent needs: when to call, why it matters, and what breaks versus what keeps working. Nothing material is missing for a zero-parameter read tool.

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

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

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The enumerated output fields are a bonus that helps the agent interpret results, though the output schema already covers them.

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 ('Get the account's AI spend and budget') and then enumerates exactly what is returned: spend this period, included credits, budget cap, and blocked status with reason. No sibling tool in the list touches billing or budget, so the agent can route here unambiguously.

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 ('Call this before a long series of prompts to check remaining budget') and the reason ('dispatch fails once a spend ceiling is reached'). It also scopes the consequence — only agent runs stop, while write_file, exec, start_app and deploy keep working — so the agent knows when the check matters and when it does not.

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 safety flags, yet the description discloses the resulting state (always private, new slug and URL, build starts immediately), the env-var binding rule, the absence of a .env file, and the blocking condition that the app won't run until secrets are set. That is substantial behavior beyond 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 purpose, then size caveat, then post-conditions, then env-var semantics. Every clause carries operational information; nothing is padding despite the length.

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

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

For a non-idempotent, open-world write with an output schema present, the description covers the full lifecycle of the call: input constraint, side effects, resulting visibility, and the follow-up action required before the app runs. An agent can invoke it correctly and know what to do next.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: bundle must be base64 and is subject to a body size limit with a better path for large bundles, and name falls back to the bundle value. server_id gains no extra context 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?

Opens with a specific verb+resource ('Recreate a project on a server from a bundle') and immediately ties it to the producing sibling, export_project. That pairing makes it unmistakable versus create_project or init_project without opening any schema.

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

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

Explicitly routes large bundles to the dashboard upload path due to request-body size limits, and directs the agent to set_secret afterward for missing env vars. What's missing is an explicit statement of when to prefer create_project over import, though the bundle prerequisite implies it.

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 context beyond annotations: the agent-side install/start/verify sequence and the run_id return path. But annotations declare destructiveHint=true and idempotentHint=false, and the description never says the bring-up mutates server state or that re-invoking restarts rather than resumes cleanly — the 'start or resume' phrasing arguably softens the non-idempotent trait without explaining 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?

Three sentences, front-loaded with purpose, then routing, then the polling pointer — minimal waste. The middle sentence packs several claims but each earns its place.

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

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

Output schema exists and the description still points to get_run for polling, so return handling is covered. The main gap is that the destructive/non-idempotent profile from annotations is not elaborated, which matters for a tool that installs packages and starts processes on a server.

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

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

Schema coverage is 100%, so both parameters are already documented. The description restates proceed ('continue past still-missing optional secrets') with only the added nuance that the secrets are optional, and adds nothing for project_id beyond the schema's pointer to create_project/list_projects.

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

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

States a specific verb and resource ('Start or resume bring-up for a project') and enumerates what the operation actually does: installs dependencies, starts the app, confirms it responds. It also distinguishes itself from the closest sibling by name ('Not for a project whose files you wrote yourself: start that one with start_app').

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

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

Gives an explicit when-to-use ('seeded from a git/archive source'), an explicit when-not-to-use with the alternative tool named ('start_app'), and a follow-up action ('poll with get_run'). The proceed flag condition is also stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior information: that omitted project_id widens the scope to the entire server workspace and that returned paths are relative to the project — a non-obvious output nuance. It stops short of noting any listing limits or pagination.

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

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

Two sentences, zero waste, with the scoping rule front-loaded ahead of the optional-parameter explanation. Nothing is repeated or padded.

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

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

With only two well-documented parameters, full annotation coverage, and an output schema handling return values, the description covers nearly everything an agent needs. A minor gap remains around whether the listing recurses into subdirectories or has any size/limit 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 coverage is 100%, so both parameters are already documented, and the description's explanation of project_id largely restates the schema text. The one added nuance is the contrast between project-relative and whole-workspace listing, which is the baseline-plus credit for a fully covered schema.

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

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

The description uses a specific verb+resource ('List paths in the server's workspace') and immediately scopes the behavior via project_id, so an agent knows exactly what this returns. It does not explicitly name a sibling tool to differentiate from (e.g., list_projects or read_file), which keeps it just short of a 5.

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

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

It gives a concrete conditional rule: pass project_id for one project's folder, omit it for the whole workspace. However, it offers no guidance on when to reach for this tool versus alternatives like list_projects, list_servers, or read_file — usage is implied rather than stated against the sibling set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, and an output schema exists, so the description's burden is light. It adds a workflow intent (pre-create inspection) but says nothing about result volume, ordering, or pagination.

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

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

Two short sentences, zero filler, with the core action front-loaded and the filter rationale immediately after.

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

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

For a single optional-parameter read tool with full annotation coverage and an output schema, the description is sufficient to call it correctly. Only minor gaps remain around return set size and ordering.

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 server_id description already states 'Optional. If provided, only projects on that server are returned.' The tool description restates the same filtering behavior with intent rather than adding format or semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("List projects") and adds the scope of the optional filter. It doesn't contrast itself with get_project or list_servers, so an agent must infer the boundary from names alone.

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

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

The second sentence gives a concrete use case for the filter — checking what already exists on a server before creating a new project — which implicitly points to create_project. No explicit when-not or exclusion guidance is offered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds genuinely new behavioral information beyond that: it never returns secret values, only a masked hint — a critical disclosure that prevents the agent from assuming it can retrieve usable credentials.

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: the first defines scope and returned fields, the second front-loads the most important safety fact ('Never returns values'). 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?

An output schema exists, so return structure needn't be explained, and the description still contributes the masked-hint caveat. The only gap is pagination/ordering behavior, which matters for a listing tool but is minor here.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description correctly implies a full account-wide listing with no filtering options.

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 account's secrets') and enumerates what is returned (keys, notes, bindings to servers/projects). This clearly separates it from set_secret/delete_secret/attach_secret, though it never names a sibling explicitly.

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

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

Usage is only implied by the verb 'List'; there is no explicit 'use this when...' or pointer to an alternative tool. For a no-parameter listing tool this is adequate, but it leaves the agent to infer the trigger condition.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the returned field set and decodes the 'kind' values ('standard' vs 'browser'), which is useful domain context beyond the annotations, but says nothing about ordering, pagination, or what an empty result means.

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

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

Two sentences, front-loaded with the core action and field list, with the glossary sentence appended where it is needed. No filler, though the kind sentence is slightly terse in phrasing.

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 structure, and it still summarizes the fields. For a zero-param read tool with full annotations, it is essentially complete; only result-ordering details are absent, which is minor.

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

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

The tool takes zero parameters, so per the baseline this is a 4. The kind explanation pertains to a returned value rather than an input parameter, so it neither helps nor hurts this dimension.

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 and enumerates the fields returned (tier, kind, status, sharing, project count), which is more informative than the bare title. It doesn't explicitly contrast with get_server, but the list-vs-fetch distinction is implied clearly enough.

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

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

Usage is only implied by the verb 'List'; there is no statement of when to call this versus get_server for a single server or list_projects. The kind glossary hints at interpreting results but offers no selection guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely behavioral context beyond that: it discloses the ordering convention (import templates first), the source_kind values that distinguish them, and that no filtering is available — information an output schema alone would not convey.

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

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

Four sentences, front-loaded with purpose and then the entry taxonomy, ending with the actionable next step. The enumeration of fields (id, label, description, visibility, lifecycle) is mildly redundant with the output schema, which is the only real slack.

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 zero-parameter read-only tool with an output schema and full annotation coverage needs exactly this: what it returns, how to read the ordering, and what to do with the result. Nothing an agent needs in order 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?

Zero parameters, so baseline is 4. The description does not invent phantom parameters and correctly frames the returned `id` as the value to feed into create_project's `template` argument, linking the two tools' parameter semantics.

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

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

States a specific verb and resource ("List the available project starters") and immediately characterizes what a template is, separating it from the sibling list_projects which returns actual projects. An 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 a concrete downstream use: pass the id as `template` to create_project to pre-pick defaults. That is clear context for when to call it, though it states no exclusions or conditions under which a different tool would be preferred.

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

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

The annotations already flag destructive and openWorld, and the description adds substantive context beyond them: it spends the account's AI budget, it returns a run_id to poll with get_run, each call starts a fresh conversation unless follow_up_of is passed, and project scoping behavior. That async, stateful, cost-bearing profile is exactly what an agent needs and is not derivable from annotations.

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

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

The core action and cost warning are front-loaded, and every sentence carries information. It is on the long side at six sentences, and the project_id/follow_up_of guidance partly duplicates schema descriptions, but nothing is filler.

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

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

For a non-idempotent, destructive, open-world tool with four parameters, the description covers cost, async polling via get_run, conversation continuity, and scoping. An output schema exists, so omitting return-value detail is appropriate, and it still names run_id and resumed.

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 the consequence of omitting project_id (whole-server workspace, e.g. scaffolding a new project) and the conversational semantics of follow_up_of (memory is retained, and a run continues where the earlier one ran). These are effects, not restatements of the schema text.

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

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

States a specific verb and resource (send a freeform prompt to the on-server agent) and then enumerates the agent's capabilities (plans, writes code, runs commands, ships). It explicitly contrasts itself with the manual siblings write_file, exec, start_app and deploy, so an agent can separate this tool from them without reading 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 conditions: when the user asks for the on-server agent, to continue a run it started, to answer a run awaiting_input, or to request changes to what a run built. It also gives a when-not rule (build it yourself with the free tools) and names those alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and closed-world scope, so the safety profile is covered. The description adds real behavioral value beyond that by warning that plain-text mode will corrupt non-text bytes — a failure mode no annotation encodes. It stops short of covering error behavior for missing files.

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, each carrying distinct information (scope, path resolution, binary handling), with the primary purpose front-loaded. 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?

Output schema exists, so return values needn't be described. With four params, full schema coverage, and an output schema, the remaining burden on the description is path resolution and binary safety — both are present. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the interaction between project_id and path resolution, which is the one semantic subtlety not obvious from the fields alone. The encoding advice also reinforces the enum's purpose.

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

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

States a specific verb and resource ('Read a file from the server's workspace') and immediately scopes it to the workspace, which cleanly separates it from siblings like list_files and write_file. An agent knows exactly what it retrieves without opening the schema.

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

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

Gives concrete conditional guidance: supply project_id to resolve inside a project folder, omit it for the workspace root, and use base64 for binary files. It doesn't mention using list_files first to discover paths, but the core when/how conditions are explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, and the description is consistent with all three. It adds real context beyond them: upsert semantics (one secret per key, setting an existing key overwrites its value) and a security trait not encoded anywhere else — values are write-only and never returned by any tool. Auth/permission requirements are the main omission.

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 the core action and resource first, then the upsert rule, then the write-only constraint, then the sibling pointer. No filler and no repetition of the title or 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 and all three parameters documented in the schema, the description covers everything an agent needs: what it writes, overwrite behavior, that values can't be read back, and how to make the secret usable. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description still adds meaning: the key is unique and re-setting it mutates rather than duplicates, and the value is unrecoverable. Those are behavioral implications the schema's terse field descriptions don't convey.

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 pair and resource ("Create or update a secret") plus a concrete definition of the resource ("an env var, key → value") on an explicit scope (the account). It also disambiguates the create-vs-update behavior in the same breath, which an agent can use to tell it apart from attach_secret, list_secrets, and delete_secret.

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 follow-up step: "Use attach_secret to bind it to a server or project," which is the main ambiguity an agent would have with a sibling named attach_secret. It doesn't address when to prefer delete_secret or list_secrets, but the create/update vs bind distinction is the one that matters for correct selection.

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: background process execution with PORT injected, persistence across restarts, a ~10 second port-readiness wait, what is returned (answering state, log tail, URL), and the visibility prerequisite for the URL to serve. It also carries a genuine safety warning that serving the project folder would expose .server4agent/env secrets, which directly explains the destructive/open-world profile.

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

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

Front-loads what the tool does and how it behaves, then moves to caveats and the security warning at the end. It is dense but long; the static-file example and URL-visibility note are justified, though the paragraph could be broken into shorter units for faster scanning.

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 prerequisites (files written, visibility public via update_project), execution semantics, timing expectations, and restart behavior; an output schema exists so the description need not detail return values beyond its one-line mention. 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%, so the baseline is 3, but the description adds semantics the schema does not: the name field controls restart identity and isolating a worker from the web app, and the command must run in the foreground without a trailing & and bind to the injected PORT. It repeats the 'web' default rather than adding to it, keeping it from a 5.

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

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

States a specific verb and resource ('Start a project's app') plus its lifecycle meaning ('the step that puts a project online after its files are written') and that re-invocation restarts. An agent can distinguish it from write_file, exec, and deploy without opening a schema.

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

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

Gives clear sequencing cues (use after files are written; call again with the same name to pick up changed code) and a concrete static-file recipe. It does not explicitly say when to prefer this over sibling alternatives like exec or deploy, so it stops short of full when/when-not guidance.

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

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

Annotations already declare non-read-only, destructive, open-world, non-idempotent, so the safety profile is covered. The description still adds real value: the staged pipeline (plan, scaffold, write, install, build, test, start on project's port), the budget consumption, and the polling contract with get_build. It does not say what on-disk state a build may overwrite despite destructiveHint=true, which keeps it below a 5.

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

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

Front-loaded with purpose and the usage gate, then lifecycle, return values, and parameter behavior in a logical order. It is dense and runs long in a single block, with the project_id guidance partly duplicating the schema, but no sentence is filler.

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

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

For a destructive, open-world agent-launching tool, the description covers cost, pipeline stages, return values (build_id, run_id), polling target, and the project-vs-root branching. An output schema exists, so return-value explanation need not be exhaustive, and nothing required to invoke it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters are already documented, including project_id's workspace-folder behavior. The description largely restates that and adds only the workflow hint that a project build is followed by deploy; it offers no additional format or constraint detail. 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 ('Have the on-server agent build a web page, site, app or API from a plain-language goal') and immediately names the sibling alternatives (write_file, exec, start_app, deploy) that do the same job manually. An agent can distinguish this from prompt or deploy 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 an explicit when-to-use gate ('Use it only when the user asks for that agent') plus the cost signal ('counts against the AI budget like prompt') and the do-it-yourself fallback. This is exactly the routing information an agent needs before choosing between start_build and prompt/exec.

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 and idempotent=true. The description adds non-obvious behavior beyond the schema: the slug and URL do not change on rename or visibility change, and run_plan is a stored intention rather than an action. What is actually destroyed by the destructive hint (e.g. wholesale run_plan replacement, password invalidation) is left to the 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?

Two sentences, the operation scope first and the run_plan/init_project caveat second. Nothing redundant; every clause carries distinct information.

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

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

With an output schema present and fully documented parameters, the description only needs to convey scope and the run_plan caveat, which it does. Minor gap: the destructive nature of wholesale run_plan replacement and password invalidation isn't surfaced at the top level, though the schema covers it.

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

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

Schema description coverage is 100% and the parameter descriptions are richer than the summary text (e.g. the access enum semantics, port rules, password behavior). The description mostly restates the field list, 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?

Specific verb (update/rename/change) plus resource and an enumeration of the mutable facets: name, description, visibility, access, lifecycle, run plan. It also explicitly distinguishes itself from init_project, so an agent can tell the two apart 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?

States clearly that setting run_plan only records intent and that init_project should be called when a rebuild is wanted, which is a real routing decision. It does not, however, cover other nearby alternatives (deploy, start_app, update_server) or when not to update at all.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds no behavioral context such as what gets disrupted or that project_sharing only applies to the next run bakes the fact that the update is not retroactively applied. That crucial timing detail lives only in the schema, so the description contributes nothing beyond 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?

A single front-loaded sentence with no padding. Slightly under-specified rather than verbose, but structurally sound.

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

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

An output schema and full annotation set carry much of the burden, so the tool is callable. Still, the description omits the delayed-effect behavior of project_sharing and uses a field name that doesn't match the schema, leaving avoidable ambiguity for a destructive mutation.

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

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

Schema coverage is 100% and the schema already documents server_id, region, and the project_sharing semantics in detail. The description only loosely paraphrases the fields and its 'nickname' phrasing actually diverges from the schema's 'task' parameter, so it adds no meaning 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 (update) and resource (server) and enumerates the affected fields, which separates it from siblings such as update_project or control_server. The one weakness is the loose field label 'nickname', which does not match the actual parameter name 'task'.

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

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

No indication of when to use this versus alternatives like control_server or get_server, and no prerequisites such as needing the server_id from list_servers. The agent must infer usage entirely.

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

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

Adds substantial context beyond annotations: the overwrite risk, the 512 KB per-call limit, encoding corruption warnings, and the non-obvious fact that writing does not serve a project until start_app runs. These behavioral traits are exactly what 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?

Well front-loaded, with the core action first and constraints/follow-up after. It is fairly dense with several distinct clauses, but each sentence carries actionable information, so little is wasted.

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

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

For a mutation tool with an output schema, the description covers the safety profile, size limits, encoding, path resolution and the start_app follow-up. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% so the schema already documents parameters, but the description adds value by explaining the binary-corruption rationale for base64 and path resolution relative to project vs workspace root. It reinforces and slightly exceeds the schema's own descriptions.

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

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

States a specific verb and resource ('Write or overwrite a file') and scopes it to the server's workspace, distinguishing it from read_file, delete_file and list_files. An agent can tell exactly what it does and its overwrite semantics 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 tells when to use base64 vs utf8, when to split large content (512 KB cap, or fetch via exec), and critically routes the agent to start_app after writing files. It names alternatives and the conditions that select them.

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