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?

Annotations already indicate idempotency and non-destructive behavior. The description adds valuable behavioral context: rolling restart with zero downtime and that it reruns the current build. This goes beyond annotation data, though auth/failure specifics are absent.

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

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

Two sentences, front-loaded with the core purpose and behavior. Every clause earns its place, with no redundancy 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?

For a simple tool with one parameter and full annotations, the description covers purpose, usage, and key behavioral traits. No output schema exists, but the tool's simplicity means this is sufficiently 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 already provides high coverage (100%) and a meaningful description for app_id ('returned by list_apps'). The description adds only that the app must exist, which is implied; no extra parameter-level context is provided.

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 restarts an existing app with a specific verb and resource. It distinguishes from sibling deploy_app by explicitly noting it reruns the current build and does not pull new code.

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

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

It gives explicit guidance on when to call: after changing configuration or to recover a stuck/misbehaving app. It also implicitly contrasts with deploy_app for code updates, clarifying appropriate use cases.

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

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

Annotations already indicate mutability and idempotency; the description adds valuable behavioral details: the operation is applied with a zero-downtime rolling update and the new size must fit the available compute pool. This goes beyond the structured annotation hints without contradicting them.

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 concise sentences with the main action front-loaded. No redundant words, and each sentence contributes to purpose, usage, or behavior.

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

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

For a tool with two simple parameters and good annotations, the description covers purpose, when to use, prerequisite steps, constraints, and deployment behavior. It is complete enough for an agent to invoke correctly without additional information.

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

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

Schema coverage is 100% with meaningful descriptions for both parameters. The description adds the extra constraint that the new memory size must fit the available compute pool, which is not present in the schema, and reinforces the relationship to get_resource_usage.

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

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

The description uses a specific verb ('Change') and clearly identifies the resource ('memory one app gets'), distinguishing it from sibling tools like resize_database and resize_database_storage. It also states the exact use cases (OOM or user request to resize), making the purpose 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 explicitly states when to call ('when an app is running out of memory (OOM) or the user asks to make an app bigger or smaller') and provides a prerequisite ('call get_resource_usage first'). It does not mention when-not-to-use or alternatives, but the context is clear 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?

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?

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.