Dockhold

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

Annotations are all false, and the description adds behavioral context: deployment returns an app ID, private repos enable auto-deploy, and the app builds automatically. It also mentions the required token scope and suggests polling get_app_status. It does not discuss idempotency or duplicate handling, but given annotations, this is adequate.

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 purpose and then provides conditional logic. It is concise but could be improved with bullet points or clearer separation of public vs. private paths. No redundant sentences.

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 4 parameters, no output schema, and moderate complexity, the description covers return value, prerequisites, polling, auto-deploy, and auth. It does not mention error scenarios or name uniqueness but is sufficiently complete for most agents.

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%, but the description adds meaning beyond the schema. It explains how repo_url distinguishes public/private repos, how github_installation_id is obtained from list_github_repos, and that with_database defaults to false. The auto-deploy behavior for private repos is also mentioned, which is not in 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 uses specific verbs ('Deploy a GitHub repository as a live web app') and clearly states the purpose: putting an app online, getting a shareable HTTPS URL, or hosting a demo. It distinguishes itself from siblings like deploy_group, get_app_status, and list_github_repos by focusing on the deployment action.

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 put an app online...'). It provides conditional guidance for public vs. private repos, including prerequisites (list_github_repos for private repos). However, it does not explicitly contrast with deploy_group or mention when not to use this tool, leaving slight ambiguity.

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?

With annotations only indicating non-readOnly and non-idempotent behavior, the description fully discloses key traits: each service gets its own URL, environment variable token substitution for inter-service URLs, database injection via 'db':'enable', parallel builds, and the need to poll for status. No annotation contradiction 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?

The description is a single concise paragraph with no wasted words. It front-loads the purpose, then gives usage guidance, then explains mechanisms. Every sentence adds essential information.

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

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

Given the complex nested schema and no output schema, the description covers the key behavioral aspects: parallel builds, polling requirement, URL injection, and database enablement. It indirectly reveals that the response includes `app_id`s. However, it does not explicitly describe the return format or error scenarios, which would make it fully 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?

Schema description coverage is 100%, so baseline is 3. The description adds some usage context (e.g., wiring services via token, frontend vs backend database needs) but largely restates what the schema already explains. The added value is marginal, not substantial enough to raise the score.

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 deploys multiple connected services together, using the verb 'deploy' and resource 'service group'. It distinguishes from the sibling tool 'deploy_app' by explicitly stating it is for projects split across multiple repos, thus meeting the highest standard.

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 use this tool ('when the user's project is split across multiple repos that must talk to each other') and when to use the alternative ('for a single repo use deploy_app'). It also instructs to poll `get_app_status` with each returned `app_id`, providing clear post-deployment steps.

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 readOnly=true, destructive=false. Description adds context that logs 'usually name the cause,' which is helpful beyond annotations but does not disclose additional behavioral traits like rate limits or data recency.

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: first sentence states purpose, second adds usage context. Every word earns its place; no 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?

Given no output schema, the description explains when to use and what it returns (logs). It lacks detail on log format or pagination, but for a simple retrieval tool with rich schema and annotations, it is largely 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?

Schema description coverage is 100%, so baseline is 3. Description adds no extra meaning beyond 'most recent' (which aligns with the tail parameter) but does not elaborate on parameter formats or constraints.

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?

Explicitly states 'Get the most recent runtime logs for one app.' with clear verb (get) and resource (runtime logs). Distinguishes from siblings like get_app_status and list_apps by specifying logs.

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 scenarios: 'when an app is crashing, returning errors, or a deploy succeeded but the app misbehaves.' This guides the agent effectively.

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, destructiveHint=false. The description adds behavioral context by specifying the returned fields and use cases, without contradicting the annotations. It does not mention any additional side effects or permissions.

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 key output fields, and contains no extraneous information. Every sentence adds value.

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 simple single-parameter interface, lack of output schema, and clear annotations, the description fully covers what the tool does and when to call it. No additional information is necessary.

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%; the schema already describes app_id as 'The app id returned by list_apps'. The description implies the parameter's role but adds no new semantic detail beyond the schema. 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 uses a specific verb ('Get') and resource ('detailed status for one app'), listing concrete fields (deploy status, URL, last deployed commit, error message). It effectively distinguishes from sibling tools like list_apps (which lists all apps) and get_app_logs (for logs).

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 use the tool: 'to check whether a deploy has finished, to get an app's live URL, or to see why an app is in error.' This provides clear context for use, though it doesn't explicitly list when not to use it or name 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 and idempotentHint, so the description adds value by detailing exactly what data is returned (bought/used/free per pool, per-app sizes). No contradictions.

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

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

Two sentences, the main purpose is front-loaded. The second sentence is somewhat long but packs essential usage guidance; slight room for splitting.

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?

Despite no output schema, the description fully explains what the output contains and provides two key use cases (pre-resize check, explaining failures). No missing context.

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?

No parameters exist (0 params, 100% schema coverage), baseline 4. Description mentions 'allowed sizes come from its steps fields' which is relevant context but not parameter documentation.

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 specifies the exact resources (compute, database-RAM, storage pools) and what is shown (bought, used, free, per-app sizes), clearly distinguishing it from sibling tools like resize_app.

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

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

Explicit instruction to call before any resize tool, with reasoning (allowed sizes from steps fields) and additional user-explanation use case (why app ran out of memory). Provides both when-to-use and 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 indicate read-only, idempotent, non-destructive behavior. The description adds value by specifying the output fields (id, status, URL, source repo), going beyond what annotations 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?

Two sentences that are front-loaded with the primary purpose and followed by usage guidance. No wasted words.

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 list tool with no parameters, the description fully covers what it does, when to use it, and what output to expect, 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 has no parameters, so the description inherently covers all aspects. Baseline is 4 for zero-parameter tools.

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 it lists apps in the Dockhold account with specific fields (id, status, URL, source repo). This verb+resource combination is distinct from sibling tools like deploy_app or get_app_logs.

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 instructs to call this first when the user asks about apps or when an app_id is needed, providing clear usage context and prioritizing it as a prerequisite for other 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 indicate readOnly, idempotent, and non-destructive. Description adds context about listing across all installations and the relationship with deploy_app, which enhances transparency beyond annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficiently conveys key information.

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

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

Given zero parameters and no output schema, the description is fully complete: explains when, why, and how to use the result with deploy_app.

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?

No parameters, so baseline of 4 applies. Description adds no param info because none exist; schema coverage is 100%.

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?

Clearly states it lists connected GitHub repos, distinguishes from sibling tools by specifying its role before deploy_app for private repos.

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

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

Explicitly tells when to call (before deploy_app for private repos, when user asks about deployable repos) and how to use the results (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 context beyond annotations: rolling restart, zero downtime, and no new code. Consistent with idempotent and non-destructive hints.

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

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

Two sentences, front-loaded, no wasted words.

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 single parameter, no output schema, and annotations, description covers all needed context for correct invocation.

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

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

Schema already covers app_id. Description adds helpful sourcing ('returned by list_apps'). Baseline 3 plus extra value.

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?

Clear verb 'Restart' and resource 'existing app' with distinguishing details: rolling restart, zero downtime, reruns current build.

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

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

Explicitly states when to use: after configuration changes or to recover a stuck/misbehaving app. Contrasts with deploy by noting it does not pull new code.

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 indicate idempotent and non-destructive; description adds 'zero-downtime rolling update' and constraint about fitting into compute pool, enriching behavioral context.

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 waste, purpose first, then usage context, then behavioral detail. Efficient 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?

Given the tool's simplicity (2 params, no output schema), the description covers all needed aspects: purpose, when to use, prerequisites, and behavior. 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?

Input schema covers both params with descriptions; description reinforces the constraint for memory_mb (must be from get_resource_usage), adding value beyond 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 ('Change how much memory') and resource ('one app gets'), distinguishing it from sibling tools like resize_database or deploy_app.

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

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

Explicitly states when to call (OOM or user request), what values are valid (from get_resource_usage), and prerequisite (call get_resource_usage first). Provides clear 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?

Warns about database restart and connection loss, which is critical behavioral info beyond annotations. Also states prerequisite 'Only works if the app has a managed database.' Annotations already provide idempotentHint=true and non-destructive hint.

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?

Concise: few sentences, front-loaded with purpose, then guidance, then warning. Every sentence adds value with no 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?

Covers prerequisites, side effects, and usage context well. No output schema, but for an idempotent mutation tool, return values are less critical. Could mention response format, but not a major gap.

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?

Both parameters are described: app_id references list_apps, db_ram_mb explains how to find valid sizes via get_resource_usage. This adds meaning beyond the schema descriptions. Schema coverage is 100%.

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 'Change how much memory an app's managed database gets,' which is a specific verb+resource. It distinguishes itself from sibling tools like resize_app 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?

Provides explicit when to use ('when the database is slow or out of memory') and constraints (size must match steps_mb, fits in pool). Does not explicitly mention when not to use or alternatives, but gives clear 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?

Discloses key behaviors beyond annotations: 'GROW-ONLY: you can increase storage but never shrink it', 'Applied online with no database restart', and 'Only works if the app has a managed database'. No contradiction with annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false).

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

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

Three sentences, front-loaded with purpose. Each sentence serves a distinct purpose: purpose, usage trigger, parameter constraint, online nature, precondition. No wasted words.

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 all necessary information: purpose, when to use, parameter constraints, behavioral traits, and prerequisites. With no output schema, return values are omitted, which is acceptable. Complete for a straightforward grow operation.

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%, but the description adds critical context for both parameters: for storage_gb, it explains it must come from get_resource_usage's storage.steps_gb and must be at least current size. This goes beyond the schema descriptions.

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

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

Clearly states 'Grow the disk of an app's managed database' with specific verb and resource. The description reinforces that it is grow-only, distinguishing it from any potential shrink operation. Sibling tool 'resize_database' exists, but the focus on disk growth sets it apart.

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

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

Explicitly tells when to use: 'Call this when the database is running out of disk space.' Provides guidance on parameter selection: 'storage_gb must be one of the sizes get_resource_usage reports' and 'fit your storage pool.' No alternative tools mentioned, but the context is clear.

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 provide idempotentHint=true, and the description adds behavioral context: the tool 'rolls out' the change and 'rejects secret-looking keys.' This goes beyond the annotations, though it does not detail what happens on re-setting a variable or if a restart is triggered. 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 sentences achieve full clarity. The first sentence identifies the core action and scope ('Set... and roll it out'), and the second provides usage guidelines and exclusion. No wasted words.

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 mutation tool with three required parameters and no output schema, the description covers the essential points: what it does, when to use it, and a key constraint. It could mention the effect on already-existing variables, but the idempotentHint and lack of destructive hint imply it is safe. Overall adequate.

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 concise descriptions. The description adds value by providing examples of valid keys (LOG_LEVEL, feature flag) and the constraint that secret-looking keys are rejected, which is not in the schema. This enhances understanding beyond the bare 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 tool's action: 'Set a single environment variable on an app and roll it out.' It uses a specific verb ('set') and resource ('environment variable on an app'). It distinguishes itself from sibling tools like deploy_app or get_app_logs by focusing on configuration variables, not deployment or retrieval.

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 guidance on when to use ('when an app needs plain configuration such as LOG_LEVEL or a feature flag') and when not to ('For secrets... use the Secrets section of the Dockhold dashboard instead'). It also explicitly states that the tool 'rejects secret-looking keys,' providing a clear exclusion criterion.

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