Dockhold

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

The annotations only indicate readOnly=false and destructive=false, but the description adds critical behavioral details: private repo deployments enable auto-deploy on future pushes, apps build and come online automatically, users should poll get_app_status, a deploy scope token is required, and it returns the new app id. This goes well beyond the structured 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 a single paragraph that front-loads the core purpose, then logically covers when to use, parameter requirements, behavioral notes, and limitations. Every sentence adds value—no filler. Despite its length, it remains organized and easy to scan.

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

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

The description addresses all key aspects: purpose, usage conditions, parameters, deployment behavior, permission requirements, and fallback for non-repo code. It even tells the user what to do after deployment (poll get_app_status). Given that there is no output schema, it appropriately mentions the return value. This is fully complete for the tool's complexity.

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

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

The input schema already documents all four parameters (100% coverage), but the description adds meaningful context: it explains the public/private repo distinction, how to obtain github_installation_id from list_github_repos, and the effect of with_database (provisioning a managed Postgres database). This enriches the parameters 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 opens with a clear, specific action: 'Deploy a GitHub repository as a live web app on Dockhold.' It distinguishes from sibling tools like redeploy_app by focusing on initial deployment, and explicitly states when to call it ('when the user wants to put an app online, get a shareable HTTPS URL, or host a demo'). This fully clarifies the tool's purpose.

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 states when to use this tool versus alternatives: 'Call this when the user wants to put an app online...' and also provides an exclusion for local code with a CLI alternative ('run `npx dockhold login` then `npx dockhold deploy` in the project folder instead'). It also gives prerequisite steps for private repos (call list_github_repos first). This is excellent 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 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 declare readOnly, idempotent, and non-destructive. The description adds valuable context about what the status includes (deploy status, URL, commit, error) and clarifies that it reflects deploy state. 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?

Two concise, front-loaded sentences. The first states the action and return fields; the second provides usage guidance. No wasted words or 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?

For a simple read-only status tool with one parameter and strong annotations, the description adequately covers purpose, usage, and return fields. It even lists return data despite no output schema, making it 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 schema fully covers the single app_id parameter with a clear description ('The app id returned by list_apps'). The description does not add extra 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 tool's function: 'Get detailed status for one app' and lists specific return fields (deploy status, URL, last deployed commit, error message). It distinguishes from siblings like list_apps or get_app_logs by focusing on a single app's 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 states when to call: to check whether a deploy has finished, to get an app's live URL, or to see error reason. It doesn't mention when not to use or name alternatives, but the provided use cases are specific and actionable.

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?

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?

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?

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?

Annotations already convey idempotent and non-destructive traits. The description adds useful behavioral context: the variable is 'rolled out' and secret-looking keys are rejected. No contradiction with annotations, and the extra details go beyond what structured hints 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?

Three sentences with no fluff. The first sentence states the action, the second explains when to use, the third explains when not to use. 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 simple setter with full annotations and no output schema, the description covers purpose, usage, and limitations. A minor gap is not specifying overwrite semantics or rollout side-effects, but this is not critical for a straightforward environment variable set.

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 covers 100% of parameters with descriptions. The description enriches this by giving examples of acceptable keys (LOG_LEVEL, feature flag) and explicitly ruling out secret values, adding practical meaning to the 'key' and 'value' parameters.

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

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

The description clearly states 'Set a single environment variable on an app and roll it out,' which is a specific verb+resource action. It also distinguishes from sibling tools like deploy_app or list_apps by focusing on environment variables.

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 when-to-use guidance: 'Call this when an app needs plain configuration such as LOG_LEVEL or a feature flag.' Also gives a clear exclusion: 'For secrets... use the Secrets section... this tool rejects secret-looking keys.' This fully addresses when and when-not to use the tool.

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