Dockhold

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

Beyond the annotations (mutation, idempotent), the description discloses the restart side effect, the privacy-critical fact that 'nothing passes through your context and no value is stored again,' and the broad authorization scope ('any secret on the account to any app'). These are behavioral traits an agent cannot infer from the schema or annotations. The restart detail coexists with idempotentHint=true without a direct contradiction.

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 the core action, followed by usage conditions, a caveat with the alternative, and a security note. Every sentence carries distinct, necessary information; nothing is repeated from 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?

Covers action, side effect, when/when-not, alternative, sharing semantics, and token authorization — with annotations covering idempotency and safety. The only gap is that no output or success confirmation is described, which matters slightly more because there is no output schema.

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

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

Schema coverage is 100% and each parameter already has a descriptive comment, so the baseline is 3. The description adds value by clarifying that reusing a vault_key_name across apps means they 'share the value,' and by tying the name parameter to 'the environment variable name the app reads.' This elevates it slightly above schema-only.

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

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

States a specific verb-resource pair ('attach a secret already stored in the account vault to one app') plus the environment-variable context and the restart side effect. It explicitly separates itself from set_app_secret ('store a new value with set_app_secret... instead'), so an agent can distinguish it from its nearest sibling 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 explicit trigger conditions ('when the user says the key already exists in Dockhold', 'when a second app should use the same stored value') and points to list_secrets for discovery. It also states the exclusion — 'if the user wants separate credentials per app' — and names the alternative tool (set_app_secret). This is exactly the when/when-not guidance the dimension rewards.

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, it discloses important side effects: deploying a private repo enables auto-deploy on future pushes, the app builds and comes online automatically, and memory is taken from the user's compute pool. It also explains the rolling-update behavior of a later resize and the required deploy token scope, giving an agent a clear model of the operation's real-world impact.

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

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

The description is long but information-dense, and every sentence adds decision-relevant context. It is front-loaded with the core purpose and trigger conditions, then flows through private repos, auto-deploy behavior, memory sizing, local-code alternatives, and authentication. There is no filler or repetition.

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

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

For a mutation tool with no output schema, the description covers the key operational context an agent needs: what triggers it, what it returns, how to monitor progress, how to size compute, how to handle private vs. public repos, how to recover from local-only code, and what auth scope is required. The optional with_database parameter is already documented in the schema and does not weaken completeness.

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?

Although schema coverage is 100%, the description adds substantial meaning: it explains the public vs. private repo distinction for repo_url, tells the agent to source github_installation_id from list_github_repos, provides concrete memory sizing guidance (256 MB for static sites, 512 MB for typical Node/Python apps, more for in-memory data), and clarifies the memory_mb response semantics. This goes well beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Deploy a GitHub repository as a live web app on Dockhold.' It also lists concrete trigger intents ('put an app online, get a shareable HTTPS URL, or host a demo') and states it returns the new app id, making it easy to distinguish from siblings like redeploy_app or deploy_group.

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 explicitly says when to call the tool: when the user wants to take an app online, get a URL, or host a demo. It also gives exclusion guidance: local-only code cannot use this tool and should use `npx dockhold login` and `npx dockhold deploy` instead, and private repos require calling list_github_repos first to obtain the installation 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 do not provide explicit safety hints (all flags false), so the description carries more behavioral burden. It discloses key behaviors: each service gets its own URL, builds run in parallel, env var token replacement, database injection, and polling with app_id. However, it does not explicitly state potential side effects like replacing existing deployments or failure cleanup, which prevents 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 description is concise and well-structured, opening with the core purpose, then usage guidance, then key operational details (env wiring, db, parallel builds, polling). Every sentence earns its place without fluff or repetition of 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?

Given the complexity of a multi-service deployment tool with nested objects and no output schema, the description covers essential aspects: how to connect services, when to enable db, parallel execution, and how to track deployment status. It even references return values (app_id) and the sibling get_app_status for polling, making it sufficiently complete for an agent to invoke 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%, providing detailed descriptions for db, env, source, port, and type. The description adds meaningful context beyond the schema, such as which services typically need a database ('pure frontend doesn't need one') and how to wire services via the exact token format. This enriches the parameter guidance without redundancy.

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

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

The description clearly states the tool's purpose: 'Deploy several connected services in one go' with a concrete example ('frontend + API'). It also distinguishes from sibling tool deploy_app by explicitly noting the single-repo alternative. The verb 'deploy' and resource 'service group' are specific and unambiguous.

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

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

The description gives explicit guidance on when to use this tool: 'when the user's project is split across multiple repos that must talk to each other.' It also names the alternative: 'for a single repo use deploy_app.' Additional guidance on database provisioning and polling via get_app_status provides clear usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat safety. It adds value by explaining that logs are diagnostic ('the logs usually name the cause') and that they are the 'most recent' runtime logs, which is useful behavioral context beyond the annotations.

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

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

The description is two sentences with no fluff. The first sentence states the core function, and the second provides usage context. Every word earns its place, making it concise and well-structured.

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

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

For a simple read-only log retrieval tool with full schema coverage and strong annotations, the description provides adequate context for when to use it. It lacks details about output format or pagination, but these are not critical for the tool's purpose, so it is nearly complete.

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

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

The input schema provides 100% parameter descriptions for 'app_id' and 'tail', so the description does not need to add param semantics. It adds nothing beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Get'), the resource ('runtime logs'), and the scope ('for one app'), distinguishing it from sibling tools like deploy_app or get_app_status. It explicitly names the action and the object, leaving no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Call this when an app is crashing, returning errors, or a deploy succeeded but the app misbehaves.' It does not name alternative tools, but the context makes it clear that this is the diagnostic log tool, distinct from deployment or status tools, so it falls just short of a 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds genuinely non-obvious state-machine semantics: DEPLOYING with ready_at set means the new version is already reachable, it transitions to RUNNING once confirmed, or to ERROR with an error_message on crash. That is a meaningful behavioral disclosure beyond the annotations, though it says nothing about freshness, caching, or polling expectations.

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

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

Three sentences, each earning its place: purpose plus return fields first, use cases second, state-lifecycle nuance third. Nothing is padded and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description fully carries the burden of describing return values and does so explicitly. For a one-parameter read tool with strong annotations, an agent has everything needed to select and invoke it correctly.

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

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

There is a single parameter with 100% schema description coverage, so the baseline is 3. The description supplies no additional semantics about app_id (formats, where obtained), leaving the schema to carry it.

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

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

States a specific verb and resource ('Get detailed status for one app') and enumerates exactly what is returned: deploy status, URL, last deployed commit, and error message. This distinguishes it from siblings like get_app_logs and list_apps without needing to open either schema.

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

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

Gives three concrete use cases: checking whether a deploy finished, retrieving the live URL, and diagnosing an error state. It is strong context but stops short of naming the alternatives (e.g. use get_app_logs for stack traces) or stating when not to use it, so it does not reach a full 5.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by detailing exactly what data is returned (bought, used, free, app sizes) and why it should be called, which enriches the agent's understanding beyond the annotations.

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

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

The description is two sentences, front-loaded with the core functionality and specific data categories, followed by a concise usage directive. Every sentence earns its place without redundancy.

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

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

With no output schema, the description adequately enumerates the returned data categories and gives clear use cases, making it fully contextual for an agent selecting this tool among its siblings.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description omits parameter details correctly, and no parameter semantics are needed; the baseline of 4 is appropriate for a parameterless tool.

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

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

The description clearly states 'Show your account's compute, database-RAM, and storage pools' with specific data points (bought, used, free) and 'every app's current size'. It distinguishes itself from sibling tools by focusing on resource usage rather than deployment, logs, or resizing.

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 instructs to call it 'before any resize tool' and 'to explain to the user why an app ran out of memory or a deploy was refused for capacity,' providing clear when-to-use guidance and implicitly referencing resize tools as alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the return payload fields and the tool's role as a first-step lookup, which is beyond what annotations convey.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no redundant wording. Every clause adds meaningful information: what is listed, which fields are returned, and when to call it.

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 parameterless list tool with strong annotations, the description is complete: it names the resource, return fields, and primary use case. No output schema exists, but the return fields are explicitly listed, which adequately covers what the agent needs to know.

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

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

The tool has zero parameters, and the baseline for 0 params is 4. The description adds no parameter-specific details because there are none to describe; the empty schema already fully covers 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 states a specific verb ('List') and resource ('apps in your Dockhold account'), and enumerates the returned fields (id, status, URL, source repo). This clearly distinguishes it from sibling tools like list_github_repos and get_app_status.

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

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

Explicitly instructs when to use the tool: 'Call this first whenever the user asks about their apps, or when you need an app_id for any other tool.' This provides clear contextual guidance and positions it as a prerequisite for other app-related tools.

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

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

The annotations already mark the tool as read-only and idempotent. The description adds meaningful behavioral context beyond the annotations: it returns names only, and secret values cannot be read back through this connection at all. This is important for agents that might otherwise assume secrets are retrievable.

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

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

The description is compact and front-loaded. The first sentence states the purpose and use case, and the second sentence clarifies the critical limitation. Every sentence earns its place with no fluff.

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

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

For a simple single-parameter read-only tool with strong annotations and a clear parameter schema, the description is complete. It explains the return scope (names only), the limitation on values, and the intended usage context. No output schema exists, but the description adequately covers what the caller will get.

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 app_id parameter is already documented with a helpful description referencing list_apps. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states the operation: listing the names of secrets attached to a specific app. It also specifies the scope (names only) and differentiates this tool from set_app_secret and unset_app_secret by framing it as a pre-check before setting another 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 gives a clear use case: determine which secrets an app already has before setting another. It does not explicitly list when not to use it or name alternatives, but the context is strong enough for an agent to select it appropriately.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds meaningful context beyond annotations: lists across every installation, each repo includes an installation_id, and the private-repo deployment flow. This is useful but does not cover every possible return detail.

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, no wasted words. The main purpose is front-loaded, followed by when-to-use and how to use the returned installation_id.

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 parameterless list tool, the description covers scope ('across every installation'), use cases, and required integration with deploy_app for private repos. No output schema exists, but the description communicates the key output element (installation_id) and its purpose.

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 are no parameters and the schema is empty (100% coverage), so the description need not explain inputs. The baseline of 4 is appropriate since no parameter ambiguity exists.

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

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

The description clearly states the tool lists GitHub repos connected to Dockhold across every installation. The verb 'List' with the specific resource 'connected GitHub repos' is distinct from sibling deploy/log tools.

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

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

Provides explicit guidance: call this before deploy_app for private repos, or when the user asks which repos can be deployed. It also explains how to use the result (pass installation_id and clone URL to deploy_app).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context by explicitly stating that secret values cannot be read back through this connection at all, which is a critical behavioral constraint beyond the annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose, then adds the usage guidance and the critical limitation about values not being readable. Every sentence earns its place.

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

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

For a parameterless, read-only list tool, the description is complete. It states what is returned, what is not returned, and how to use the result. The annotations cover safety, and the sibling list provides context for alternatives.

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

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

The tool has zero parameters, so there is no schema to clarify. The description appropriately focuses on what the tool returns (names and counts) rather than parameters, which is the relevant semantic information for a parameterless tool.

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

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

The description clearly states the tool lists secret names and usage counts from the account vault, with a specific verb and resource. It also distinguishes itself from related tools like bind_app_secret and set_app_secret by clarifying it only returns names and counts, not values.

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 explicitly says to use this tool to attach an existing secret with bind_app_secret instead of asking the user for the value again. This provides clear when-to-use guidance and implicitly distinguishes it from tools that set or modify secrets.

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 meaningful behavioral detail beyond the annotations: rolling restart with zero downtime, and the critical storage caveat that the app is stopped and started instead, causing a few seconds of unreachability. This is valuable operational context the annotations do 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?

Three focused sentences with no wasted words: the purpose is front-loaded, usage guidance follows, and the important storage caveat is clearly stated. Every sentence earns its place.

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

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

Complete for a single-parameter, no-output-schema restart tool. The description covers what it does, when to call it, what it does not do, and the one significant behavioral exception (storage). No important calling context is missing.

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

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

Schema description coverage is 100% and the only parameter, app_id, is already clearly described as 'The app id returned by list_apps'. The description does not need to add parameter details, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Restart an existing app', and adds the key distinction from deployment via 'It reruns the current build; it does not pull new code.' This clearly separates it from deploy_app and other 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 when-to-use guidance: after changing configuration, or to recover an app that is stuck or misbehaving. It also implies when not to use it by stating it does not pull new code, though it does not explicitly name deploy_app as the 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 mark the tool as destructive, but the description adds crucial detail: 'no undo and no backup', confirmation required before passing confirm true, and the post-condition that the app becomes scratch space where writes are lost on restart. This substantially enriches the agent's understanding of side effects.

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 concise and well-structured: purpose first, followed by consequence, confirmation requirement, invocation triggers, and post-state. Every sentence adds useful information without 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 two-parameter tool with no output schema, the description covers prerequisites, side effects, when to call it, and the final state of the app. Nothing an agent needs to safely invoke the tool is missing.

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

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

The schema covers both parameters well, including the requirement that confirm must be true and only after user confirmation. The description adds a small operational nuance about asking the user to confirm 'in their own words', but the core parameter meaning is already provided by the schema, so 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?

The description states a specific verb and resource: 'Remove an app's storage and erase every file on it.' It clearly distinguishes the tool from siblings like set_app_storage by emphasizing permanent destruction and the resulting scratch-space state.

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 explicitly tells the agent when to call it: 'when the user asks for the storage to go, or when they want something storage rules out.' It also adds a clear confirmation precondition. However, it does not explicitly name alternatives or say when not to use the tool, so it stops short of a 5.

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

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

Beyond the annotations, the description discloses important runtime behavior: zero-downtime rolling update for apps without storage, and a stopped/started cycle with temporary unreachability for apps with storage. This is valuable operational context an agent could not infer from the schema or annotations. No contradiction with annotations exists.

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 with no filler. The purpose is front-loaded, the when-to-use is immediate, the key constraint is stated, and the behavioral caveat is last. Every sentence earns its place.

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

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

For a two-parameter mutation tool with no output schema, this description covers purpose, trigger conditions, parameter constraints, prerequisite steps, and runtime effects. Nothing essential is missing for an agent to select and invoke 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 the baseline is 3. The description adds extra meaning by clarifying that the new size must fit the available compute pool and that get_resource_usage should be called first, going slightly beyond the schema's mention of valid values.

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

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

States a specific verb and resource: 'Change how much memory one app gets.' It clearly focuses on a single app's memory, distinguishing it from sibling tools like resize_database and resize_database_storage.

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

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

Explicitly says when to call it: when an app is running out of memory (OOM) or the user asks to make an app bigger or smaller. It also gives a strong prerequisite: call get_resource_usage first to verify the new size fits the compute pool. It does not explicitly name alternative sibling tools, but the app-vs-database distinction is clear enough.

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

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

Beyond the annotations (which only include idempotentHint=true and destructiveHint=false), the description discloses a critical behavioral trait: the database restarts briefly, causing a temporary connection loss. It also adds the constraint that db_ram_mb must fit the pool. This is rich, valuable context 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?

The description is three sentences: purpose, usage trigger, and a warning/prerequisite. Every sentence carries essential information with no redundancy. It is appropriately front-loaded with the purpose.

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

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

For a mutation tool with no output schema, the description covers purpose, timing, prerequisites, parameter constraints, and side effects. It is complete enough for an agent to decide when to call it and what to expect.

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 adds meaningful semantics for db_ram_mb by specifying it must be one of the sizes from get_resource_usage under db_ram.steps_mb and fit the pool, which goes beyond the schema's description. No additional insight is provided for app_id, but the schema already covers it.

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

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

The description clearly states the tool's function: 'Change how much memory an app's managed database gets.' The verb 'change' plus resource 'managed database memory' is specific, and it distinguishes from siblings like resize_database_storage (which resizes storage) and resize_app (which resizes app resources).

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

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

It explicitly says when to use it ('Call this when the database is slow or out of memory') and gives a prerequisite ('Only works if the app has a managed database'). It doesn't explicitly mention when not to use it or point to alternatives, but the context and sibling names provide sufficient distinction.

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

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

Discloses key behaviors beyond the annotations: GROW-ONLY semantic, online operation with no restart, and the requirement that storage_gb must come from specific reported sizes. No contradiction with annotations.

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

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

Three sentences front-load the purpose, then constraints; no filler. Every sentence earns its place.

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

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

Covers purpose, trigger, constraints, operational behavior, and preconditions. No output schema needed; the description adequately prepares the agent for invocation.

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

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

Schema already provides full descriptions for app_id and storage_gb; the description reiterates the grow-only constraint but adds the 'fit your storage pool' requirement, offering minimal extra value 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?

The description clearly states the verb 'Grow' and the resource 'the disk of an app's managed database', distinguishing it from sibling tools like resize_database by focusing on storage/disk. The title reinforces this.

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

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

Provides an explicit trigger ('Call this when the database is running out of disk space') and a precondition ('Only works if the app has a managed database'), but does not name alternative tools for different resize scenarios.

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

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

Beyond the annotations, the description discloses that the value is encrypted at rest, injected into the environment, triggers a restart, takes effect on next boot, and can never be read back through this connection. It also warns that the token can write secrets to every app on the account and that conflicting vault key names cause a refusal. This is far more than annotations alone provide.

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

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

The description is long but every sentence carries operational or safety-critical information. It is front-loaded with the core purpose and then layers in timing, retrieval limitations, permission scope, and edge-case behavior. Nothing feels redundant or 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?

Given four parameters, no output schema, and the sensitivity of the operation, the description covers the full calling picture: when to use it, what happens to the value, when to call it, what to warn the user about, and how to handle vault key conflicts. An agent has everything needed to invoke it correctly and safely.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds valuable context beyond the schema, especially the vault_key_name conflict behavior and the fact that the value is exposed via the environment under the given name. This pushes it 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?

The description states a specific verb and resource: storing a sensitive value for one app. It explicitly distinguishes itself from set_app_variable, making the tool's role unmistakable even among many sibling tools.

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

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

The description gives explicit when-to-use guidance: prefer this over set_app_variable whenever the value would be damaging if read by someone else. It also advises calling it before telling the user the app is ready, and explains when to pass vault_key_name, so an agent knows exactly when and how to invoke 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?

The description richly discloses behavioral traits beyond the annotations: storage survives restarts/deploys, DATA_DIR is the persistent path, scratch space outside it is lost, storage can grow but never shrink, a storage-enabled app runs as a single copy, cannot have scheduled tasks, and deploys cause brief downtime. It even advises the app to flush files on SIGTERM.

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 detailed but every sentence adds essential information: purpose, use case, persistence semantics, sizing constraint, irreversible growth, user-facing consequences, and graceful shutdown guidance. It is front-loaded with the core purpose and then layers necessary caveats without fluff.

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 the tool's moderate complexity, two required parameters, and no output schema, the description covers everything an agent needs: when to call it, what prerequisites exist, how parameters are constrained, what side effects to expect, and what information the user must be told. 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 coverage is 100%, so the baseline is 3. The description adds meaningful operational context for size_gb by specifying it must come from get_resource_usage's volume.steps_gb, must fit the storage pool shared with managed databases, and that growth is one-way. This goes beyond the schema's constraint wording.

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

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

The description states a specific verb and resource: 'Give an app storage that survives restarts and deploys, or grow the storage it already has.' It clearly distinguishes this from related tools like remove_app_storage and resize_database_storage by focusing on app storage growth and persistence.

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

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

The description gives explicit when-to-use guidance: 'Call this when the app has to keep files: a SQLite database file, uploads, or anything the user expects to still be there tomorrow.' It also instructs calling get_resource_usage first, but it does not explicitly name sibling alternatives or state when not to use this tool.

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

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

Beyond the annotations (readOnly=false, idempotent=true, destructive=false), the description adds meaningful behavioral context: the operation also rolls out the change, and the tool rejects secret-looking keys. These are guardrails and side effects not visible in 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?

Three compact sentences deliver the action, the appropriate use case, and the alternative tool. No filler or redundancy; the most important guidance is front-loaded.

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

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

For a simple 3-required-param tool with no output schema, nested objects, or enums, the description provides everything needed to select and call it correctly: what it does, when to use it, and when to choose a sibling. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only illustrative examples (LOG_LEVEL, feature flag) without changing parameter meaning, so the baseline 3 is appropriate.

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

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

States a specific action: 'Set a single environment variable on an app and roll it out,' with concrete examples (LOG_LEVEL, feature flag). It clearly differentiates from set_app_secret by noting that secret-looking keys are rejected, so an agent can distinguish the tool from its sibling 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?

Explicitly tells the agent when to call it ('when an app needs plain configuration') and when not to, directing it to set_app_secret for secrets. The contrast between plain configuration and secrets gives a clear decision rule.

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

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

The description richly discloses consequences that annotations only hint at. It reveals that the app restarts, that the stored secret remains in the vault, that other apps are unaffected, and that the correct reporting semantics are 'removed from this app' rather than 'deleted.' This adds substantial behavioral context beyond the destructiveHint annotation.

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

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

Each of the four sentences earns its place: the first states the action, the second provides consequence and usage condition, the third clarifies persistence semantics, and the fourth gives reporting guidance. There is no redundancy or filler, and the key scoping is front-loaded.

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

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

For a two-required-parameter mutation with no output schema and a destructiveHint annotation, the description fully covers the operational context: side effects, persistence beyond the app, effect on sibling apps, and even expected result reporting. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already well-documented: 'name' is the environment variable name and 'app_id' is the app id from list_apps. The description adds no additional parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a precise action: 'Stop injecting a stored secret into one app.' This clearly differentiates from set_app_secret (which injects) and list_app_secrets (which enumerates). It also clarifies the exact scope ('one app') and distinguishes itself from deleting the stored value entirely.

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

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

Explicit when-to-use guidance is given: 'call this only when the app no longer needs that variable.' It also provides a when-not: the stored value should not be deleted via this tool, and deleting it is a separate dashboard action. This effectively routes the agent away from misuse.

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

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

The description adds valuable behavioral context beyond the annotations: unsetting triggers a rollout, reserved variables are protected from removal, and empty-string assignment is meaningfully different. While destructiveHint=false and the word 'Remove' could seem tension-worthy, the description scopes the operation to configuration, not data destruction, so there is no actual contradiction.

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 rollout effect in the first sentence and all routing/exclusion guidance in the remaining two. There is no filler or repetition of schema content.

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

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

For a two-parameter tool with a simple action, the description covers the necessary inputs, the rollout side effect, the key exclusions, and the secret alternative. There is no output schema, but the behavior is sufficiently unambiguous without needing to document return values.

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 input schema already describes both parameters fully (app_id and key), so the description does not need to repeat them. It adds the qualifier 'plain environment variable' to distinguish from secrets, but no extra parameter-level syntax or constraints are introduced. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description states the specific verb 'Remove' and resource 'single plain environment variable from an app', and distinguishes it from the secret-removal sibling by naming unset_app_secret. It also specifies that reserved Dockhold-managed variables cannot be removed, leaving no ambiguity about what this tool does.

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

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

It gives an explicit alternative: 'For a secret, call unset_app_secret instead.' It also clarifies that removing a variable is not the same as setting it to an empty string, and enumerates exclusions (PORT, DATABASE_URL, DATA_DIR, and the app's address), making when-to-use and when-not-to-use very clear.

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