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

Annotations already declare that this is a non-destructive, idempotent mutation with closed-world behavior. The description adds useful operational context beyond the annotations by warning that DNS configuration is a separate required step, which is non-obvious and important for correct use.

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 short sentences, front-loaded with the core action and followed by the critical prerequisite. Every sentence earns its place with no redundant or filler text.

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 a fully documented schema and informative annotations, the description supplies the key external prerequisite. It does not describe the return value or subsequent verification flow, but the core behavior needed to invoke the tool correctly is present.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description does not add parameter-specific meaning beyond the schema, making the baseline score of 3 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: adding a custom domain to an app. It is clear without opening the schema, though it does not explicitly distinguish itself from sibling tools like remove_domain, set_primary_domain, or verify_domains.

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 an important prerequisite: DNS must be configured separately via CNAME or A record. However, it does not say when to use this tool versus related domain-management siblings, nor does it describe any exclusions or follow-up steps such as verification.

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 the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower; the description still earns credit by disclosing the actual side effect -- an env var containing the connection URL is written into the app -- which is not derivable from annotations or schema. It stops short of saying whether an existing env var of the same name is overwritten, whether a redeploy/restart is required, or what the tool returns.

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

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

Two short sentences, zero filler, with the action front-loaded and the consequence immediately after. Nothing repeats the title or annotations.

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

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

Adequate for a 5-parameter mutation tool with no output schema: the effect on the app is clear, but an agent still cannot tell whether the app must be redeployed afterward, whether connecting twice or reconnecting with a different env_var_name produces duplicates, or what confirmation the call returns.

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%, including defaults for driver and env_var_name, so the schema carries parameter meaning. The description only hints at the env-var behavior implicitly via env_var_name and adds no format, constraint, or interaction detail beyond the schema -- baseline 3 applies.

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

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

States a specific verb and resource ('Connect an app to a database') and immediately explains the mechanism ('injects the connection URL as an environment variable'), which separates it from siblings like deployado_disconnect_database, deployado_set_env, and deployado_create_database without needing to open the schema.

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

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

Usage is implied by the description -- you connect an app when you want its DB URL available -- but there is no explicit when/when-not, no prerequisite that the database must already exist (deployado_create_database) and the app must exist (deployado_create_app), and no mention of the inverse deployado_disconnect_database or of deployado_set_env as an alternative for manual env vars.

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 specify readOnly=false, destructiveness=false, and idempotency=false. The description adds important behavioral context beyond annotations: repository-based apps are built with Docker and must contain a Dockerfile at the specified path, including an example for static sites. It does not mention permissions or what happens after creation, but the added Docker requirement is valuable.

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 front-loaded with the core action, then uses a clear IMPORTANT section and parameter list. The static website Dockerfile snippet is useful, though the parameter list partially repeats schema field names. Overall it is appropriately sized and 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 7-parameter creation tool with no output schema, the description covers the essential Docker build requirements, defaults, and common port choices. It leaves out what happens if repository_url is omitted, whether creation triggers deployment, and any app-name constraints, but it is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that repository_url is required for repo-based apps, clarifying defaults for dockerfile_path, build_context, and branch, and giving practical port examples for nginx and Node.js. It still does not explain name constraints or all project_id expectations, so it falls short of a 5.

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

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

The description states a specific verb and resource: 'Create a new app in a project.' This clearly distinguishes the tool from siblings like update_app, delete_app, and list_apps. An agent can identify the operation without opening the schema.

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

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

It provides clear context for when Docker/repository-based creation applies and explains how static websites should include a Dockerfile. It does not explicitly name alternatives such as update_app for existing apps, but the creation context is well established.

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 that this is a non-read-only, non-destructive, non-idempotent operation, so the safety profile is covered. The description adds useful context that backups are stored in S3, but it does not mention permissions, duplicate-name behavior, or side effects of creating a target.

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

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

Two short sentences with the core action front-loaded and no wasted wording. The S3 storage note is brief but useful.

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 schema fully describes all parameters and annotations cover the mutation safety profile, so the minimal description is not inadequate. However, for a create tool with 9 parameters and no output schema, it omits context such as whether setup prerequisites exist and what happens after creation.

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 all 9 parameters are already documented in the schema, including defaults for db_port and retention_keep_last_n. The description adds no parameter-level meaning beyond what the schema provides, which is acceptable given the high coverage.

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

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

The description states a specific verb and resource: 'Create a new database backup target.' It is clearly distinguishable from sibling tools like list_backup_targets, get_backup_target, run_backup, and restore_backup, though it does not explicitly name those alternatives.

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

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

The description implies usage through 'Create a new...' but gives no explicit guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It lacks routing context that would help an agent choose it confidently.

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

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

The annotations already declare readOnlyHint=false, idempotentHint=false, and openWorldHint=false. The description adds nothing beyond that mutation profile: it doesn't say what happens on a duplicate name, whether creation is immediately active, or what errors occur when app_id is invalid.

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 efficient sentence with no filler and the verb-resource pair is front-loaded. Its brevity is the issue in other dimensions, but this dimension is about structure and waste.

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?

This is a 6-parameter mutation tool with no output schema, yet the description never mentions return values (e.g. the new job ID), the timeout_seconds behavior, or what the cron schedule does. For a creation tool with four required parameters, this leaves agents under-informed.

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%, including a worked example for cron_expression ('0 * * * *'), so the schema carries the parameter burden. The description adds no syntax or format detail beyond what the schema already provides, which is the baseline 3 case.

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 ('Create') and resource ('cron job') scoped to 'an app'. It distinguishes itself implicitly from siblings such as update_cron_job, delete_cron_job, and run_cron_job, though it never names those alternatives.

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

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

There is no guidance on when to use this tool instead of deployado_update_cron_job or deployado_run_cron_job. No prerequisites are stated, such as the app needing to already exist or which permissions are required.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the write profile is covered. The description contributes one genuinely non-obvious behavior — the account-slug name prefix — but says nothing about provisioning time, name-collision errors, quotas, or what identity is returned.

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

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

Two short sentences with no filler, and the prefixing caveat (the most surprising fact) is placed immediately after the purpose statement where it will be read.

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

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

For a 3-parameter, fully documented, non-destructive create with no nested objects, the description covers purpose and the key naming behavior. Without an output schema, it still leaves what creation returns (database ID, host, credentials) unspecified, plus whether server_id/project_id default sensibly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real meaning beyond 'Database display name' by clarifying that the supplied name is not the final database name — it gets auto-prefixed with the account slug. It adds nothing about server_id or project_id, which the schema already handles.

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

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

States a specific verb and resource ('Create a new managed PostgreSQL database'), which cleanly separates it from sibling creation tools like deployado_create_app and deployado_create_project. It does not explicitly contrast with deployado_get_database or deployado_list_databases, but the resource noun is 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?

Usage is only implied by the verb-resource combination; there is no statement of when to create a database versus connecting to an existing one (deployado_connect_database) or how it relates to project/server association. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no mention of whether optional fields like repository_url change behavior, whether name must be unique, or what happens on success.

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

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

A single front-loaded sentence with no filler, which is efficient. The brevity costs content rather than being padded, so it scores well on structure but not perfectly.

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

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

For a non-idempotent mutation tool with no output schema, the description does not say what a created project returns, whether the name must be unique, or how optional Git fields affect the result. Given the complexity of the surrounding tool family, it should do more than restate the name.

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 all four parameters are documented in the schema, so the baseline is 3. The description contributes no additional meaning about parameter interactions (e.g., that repository_url and default_branch are optional and relate to Git linking).

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

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

States a specific verb and resource ('Create a new project'), which clearly separates it from get/list/update/delete_project siblings. However, it does not explicitly name the siblings or scope it shares with them, so differentiation is inferred rather than stated.

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

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

No indication of when to use this versus deployado_create_app, deployado_install_service, or the other create_* tools, and no prerequisites or exclusion cases are given. The agent must infer usage purely from the tool name.

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 and a closed-world profile, so the safety story is fully covered by structured data. The description adds essentially no behavioral context beyond that — nothing about what happens when no deployment is active, or about permissions — which is adequate but minimal for a trivial read.

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

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

One short sentence that front-loads the verb and the resource, with zero filler. Nothing redundant and nothing that could be trimmed.

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

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

For a single-parameter read tool with rich annotations and no output schema, the description is nearly sufficient — the resource and scope are clear. The only gap is edge-case behavior (no active deployment) and how it relates to the get_deployment sibling, which prevents a 5.

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% ('App ID (UUID)'), so the single parameter is fully documented by the schema. The description contributes no additional parameter semantics such as format quirks or ID sources, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the currently active deployment') with a clear scope ('for an app'), which is more precise than a generic list or get. It does not distinguish itself from close siblings like deployado_get_deployment (likely fetch-by-ID) or deployado_list_deployments, so the agent must infer which to pick.

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

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

Usage is only implied by the word 'currently active' — the agent can infer this is for finding the live deployment, but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_deployment or list_deployments.

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

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

Goes well beyond the destructiveHint=true/idempotentHint=false annotations by explaining what is destroyed (deployments, releases, env vars), how running containers are removed (queued agent action on the app server), the transient 409 failure mode, and that the action is irreversible. That is exactly the added behavioral context the annotations cannot carry.

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

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

Three short sentences, front-loaded with the destructive scope, then the container/queue mechanic, then the failure condition and irreversibility caveat. Every sentence contributes information an agent needs before calling.

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

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

For a single-parameter destructive tool with no output schema, the description covers blast radius, side effects, transient error handling, and reversibility — everything needed to call it safely and interpret a failure.

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

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

Only one parameter, app_id, and the schema documents it at 100% coverage ('App ID (UUID)'), so the schema does the work. The description adds no format or lookup hints beyond what the schema already states.

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 (delete) and resource (app) plus the exact cascade scope: deployments, releases, and environment variables. An agent can distinguish it from siblings like deployado_delete_project or deployado_delete_env purely on the resource and cascade described.

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

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

Gives concrete operational context: it fails with 409 deploy_in_progress while a deploy runs and should be retried after it finishes. It does not, however, point at any alternative tool or say when a non-destructive path (e.g. update_app or stopping a service) is preferable.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is carried by structured data. The description adds no context beyond that — no statement about irreversibility, cascading effects on run history, required permissions, or error conditions — so it contributes essentially nothing to behavioral understanding.

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 single sentence is front-loaded and free of padding, but its brevity reflects under-specification rather than efficiency — there is no waste because there is almost no content.

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

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

For a destructive mutation with no output schema, the description should explain effects and irreversibility. With annotations covering only the safety hint, an agent still cannot tell what deletion actually does (removes schedule only vs. history) or what it returns.

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 required parameters (app_id, cron_id) are fully documented in the schema at 100% coverage, so the schema carries parameter meaning. The description mentions neither parameter and adds no usage nuance such as whether cron_id is app-scoped.

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 is essentially the tool name and annotation title restated ('Delete a cron job'). It conveys the verb and resource but adds no distinguishing detail versus siblings such as deployado_list_cron_jobs or deployado_update_cron_job, so an agent learns nothing beyond what the identifier already says.

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

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

There is no guidance on when to use this over alternatives, no prerequisites (e.g., whether the job must be stopped first), and no warning about the destructive nature beyond what the annotation covers. Usage is only inferable from the tool name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real context beyond that: what is destroyed ('drop the database and remove all data') and that the effect is irreversible. It still omits operational behavior such as permission requirements or what happens to services currently bound to the database.

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

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

Three short sentences, front-loaded with the action and followed immediately by the consequence and irreversibility warning. No filler, no repetition of the title or schema.

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

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

For a single-parameter tool with complete annotations and full schema coverage, the description covers purpose and blast radius adequately. The one meaningful gap is dependency handling — whether a connected app must be disconnected first — which matters for a destructive 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 description coverage is 100%, so database_id (UUID) is fully documented in the schema. The description adds nothing about the identifier's format or where to obtain it, which is acceptable given the schema does that work.

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

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

States a specific verb and resource ('Permanently delete a managed PostgreSQL database'), which cleanly separates it from the delete_app / delete_project / delete_env siblings. It stops short of naming those alternatives explicitly, so it is clear but not maximally differentiated.

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 never says when to reach for this versus disconnect_database, delete_app, or restore_backup, nor does it mention prerequisites such as detaching connected apps before dropping the database. The 'cannot be undone' line is a caution, not usage routing.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — it does not say whether the deletion is reversible, whether the app must be redeployed for the change to take effect, or what happens if the key is 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?

A single front-loaded sentence with zero redundancy. It is efficient, though its brevity reflects under-specification rather than tight writing.

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 mutation with full schema coverage and annotations, the essentials are present, but the description omits the consequences of deletion and any post-delete behavior an agent would want before invoking an irreversible 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 description coverage is 100% (key = variable name, app_id = UUID), so the schema carries parameter meaning. The description implies both fields ('environment variable' and 'app') but adds no format or identifier details beyond the schema; baseline 3 applies.

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

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

States a specific verb (delete) and resource (environment variable) scoped to an app, which cleanly separates it from deployado_set_env and deployado_list_env. It does not explicitly name those siblings, so it falls short of a 5.

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

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

No guidance on when to use this versus set_env (which may overwrite) or list_env, and no prerequisites or cautions. The agent must infer usage purely from the tool name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real context beyond them: the cascade into app containers, the specific 409 deploy_in_progress conflict, and irreversibility. That is exactly the extra behavioral detail an agent needs before invoking a destructive tool.

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

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

Three short sentences, each earning its place: what is deleted, the failure mode, and the irreversibility warning. Front-loaded with the action and zero 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 single-parameter destructive tool with no output schema, the description covers scope, side effects, failure conditions, and reversibility. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter (project_id, UUID) is fully documented in the schema. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a project') plus the cascade scope ('and all its associated apps'), which distinguishes it from the sibling delete_app and delete_database tools. An agent knows exactly what is removed.

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

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

Gives a concrete precondition for failure (409 deploy_in_progress while an app is deploying) and signals caution via 'cannot be undone'. It does not explicitly route to alternatives such as deleting individual apps instead, so it falls short of full when/when-not guidance.

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

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

Goes well beyond annotations by disclosing the four-stage pipeline, immediate return with release_id, background execution, and the status state machine (queued → pending → building → ready or failed). Annotations already cover safety profile; the description adds workflow semantics an agent needs.

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

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

Front-loaded with the core action plus async note, then a compact pipeline diagram, then a bulleted follow-up guide. Slight redundancy with the schema on branch/commit_sha defaults, but overall tight and scannable.

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 mutation semantics, async build lifecycle, error/recovery paths, and downstream tool chaining. No output schema exists, and the description compensates by naming the returned release_id and its follow-up uses.

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

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

Schema coverage is 100%, so baseline is 3. The description adds resolution logic for commit_sha absent from the schema itself ('latest commit from the configured branch'), which meaningfully augments parameter behavior.

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 ('Trigger a new deployment for an app') and immediately clarifies synchronous-vs-asynchronous behavior. Distinguishable from siblings like deployado_deploy_blueprint or deployado_rollback.

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

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

Explicitly routes the agent post-call: use deployado_get_release for build status, deployado_get_build_logs on failure, deployado_get_logs for runtime logs. Also explains commit_sha default via 'if omitted, the latest commit from the configured branch is used'.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, idempotentHint=false, so the safety profile is covered structurally. The description adds almost no behavioral context beyond the name: it doesn't say what is destroyed or overwritten on redeploy, whether prerequisites like an existing server/project are needed, or how failures mid-stack are handled — significant omissions for a destructive stack-wide operation.

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

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

Two short sentences, action first, with the input-mode caveat second. Nothing is padded and the key information is front-loaded.

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

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

The tool has zero required parameters, no output schema, and is marked destructive and non-idempotent; the description doesn't resolve the most important ambiguity — which parameter combinations form a valid call, or what happens to an existing stack. Adequate for orientation, but not sufficient for confident invocation of a high-risk 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?

All five parameters are fully documented in the schema (100% coverage), so the schema carries parameter meaning. The description adds a little by framing content and repository_url as mutually exclusive alternatives, but it doesn't say whether server_id/project_id are required for either path. Baseline 3 applies.

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

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

States a specific verb and resource ('Deploy an entire application stack from a blueprint') and clarifies the two input modes. It implicitly separates itself from the single-app deployado_deploy and deployado_validate_blueprint siblings, but never names them, so sibling differentiation is left to the agent.

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

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

Usage is implied by 'from a blueprint' and by the two sourcing options (inline YAML vs GitHub URL). There is no explicit when-not guidance, no suggestion to run deployado_validate_blueprint first, and no mention of how this differs from deployado_deploy, which the agent must infer from sibling names.

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

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

Annotations already declare destructiveHint=true and non-idempotent behavior, lowering the burden. The description adds useful context by specifying that the injected environment variable is removed, but it does not clarify irreversibility, permission requirements, or what happens to an app still using the connection.

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

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

A single sentence with zero waste. The destructive effect is front-loaded alongside the action, making it easy to parse quickly.

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 two-parameter destructive tool with annotations covering safety, the description is adequate but incomplete: it does not clarify how the app is identified given the absence of an app parameter, nor does it explain whether the removal can be undone. No output schema exists, so return values need not be described.

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

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

Schema description coverage is 100%, so the schema already documents both required parameters as UUID strings. The description does not add meaning beyond the schema, and notably it mentions 'an app' while no app parameter exists, leaving the role of connection_id slightly ambiguous.

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 ('Disconnect') and resource ('an app from a database') plus the concrete effect ('removing the injected environment variable'). It is clear but does not explicitly distinguish the tool from its closest sibling, connect_database.

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 offers no when-to-use guidance, no prerequisites, and no mention of alternatives like connect_database or delete_database. Usage is only weakly implied by the tool name and action.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world scope. The description adds useful behavioral context beyond that: it is a fixed checklist, not configurable, and it returns both structured results and a roll-up. It does not describe permissions or timing beyond the deep-probe note in the schema.

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

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

The description is three efficient sentences: purpose first, returned diagnostics second, usage guidance third. Every sentence earns its place, and the most important scoping and triage guidance is front-loaded.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so explicitly by listing the roll-up contents. Combined with the schema for the deep parameter and annotations for safety, an agent has enough to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema, including UUID-or-slug input for app_id and the deep-probe semantics. The description only says "against one app" and does not add meaning beyond the schema. Baseline 3 is appropriate when the schema does the parameter-level work.

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

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

The description states a specific verb and resource: running a fixed diagnostic checklist against one app. It clearly distinguishes itself from sibling getters by describing an aggregate roll-up covering deployment status, builds, server health, HTTP probing, env vars, and placement. The CLI mirroring note adds context without becoming an alternative reference.

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

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

It gives a clear usage trigger: "Use this as the first stop when triaging 'app X is acting weird'." That establishes when to prefer this aggregate diagnostic over individual tools. It does not explicitly name alternatives or when-not to use it, which keeps it from 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 destructiveHint=true, non-idempotent, openWorld, so the safety profile is covered. The description adds real value beyond that: the 60-second timeout and the exact return contract (exit code, stdout, stderr), which an agent needs to interpret results.

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

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

Three short sentences, front-loaded with the action, then timeout and return shape. Every sentence carries information and nothing is wasted.

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

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

For a three-parameter execution tool with no output schema, the description covers purpose, timeout constraint, and return values. It could note that the app must be running or the execution context, but is otherwise sufficient to call 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 description coverage is 100%, so all three parameters are documented in the schema itself. The description adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource: execute a command inside an app's running container. This is unambiguously distinct from every sibling (logs, restart_service, deploy, etc.), and an agent can tell what it does without opening the schema.

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

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

Usage is only implied by the nature of the operation; there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. get_logs for read-only inspection). An agent can infer context but gets no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that – it does not say what "detailed information" comprises or how an unknown/invalid app_id is handled.

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

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

A single front-loaded sentence with zero waste. It is appropriately sized for a trivial getter, though the word "detailed" carries little 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?

For a one-parameter read-only getter with rich annotations and full schema coverage, minimal description is defensible. Still, there is no output schema and no hint about what fields are returned or what happens when the app does not exist.

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 single parameter is documented as "App ID (UUID)" in the schema. The description adds no meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb ("Get detailed information") and resource ("a specific app"), which is clearly distinguishable from mutating siblings like update_app or delete_app. It does not explicitly contrast with list_apps, but "a specific app" plus the required app_id makes the distinction reasonably clear.

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

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

No explicit guidance on when to use this versus deployado_list_apps (to discover IDs) or deployado_get_deployment (for deployment-level detail). Usage is only inferable from the required app_id parameter.

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 cover the safety profile (readOnlyHint, idempotent, non-destructive), so the description doesn't need to. It does add one real behavioral fact beyond them: the response bundles recent backup runs alongside target details. However, it says nothing about how many runs are returned, whether they are truncated, or what happens for an unknown target_id.

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

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

One short sentence, front-loaded with the primary result and appended with the secondary one. No filler or redundant restatement of the title.

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

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

The tool is read-only with no output schema, so the description carries some burden for describing the return shape; it names the two things returned but not their structure, the cap on 'recent' runs, or error behavior for a missing target. Adequate but leaves real gaps.

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?

Single required parameter with 100% schema description coverage ('Backup target ID (UUID)'), so the schema already carries the semantics. The description adds nothing about the ID's format or provenance, which is acceptable at this coverage level.

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

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

Specific verb and resource ('Get a backup target's details') with the added note that recent backup runs are included, which distinguishes it from the plain list tool. It does not explicitly name deployado_list_backup_targets, but the singular/plural distinction makes the difference inferable.

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

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

No statement of when to use this versus deployado_list_backup_targets, and no prerequisites (e.g., that target_id must come from the list call). The agent must infer usage from the name alone.

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/non-destructive, and the description adds real behavioral content: what the output contains (Dockerfile parsing errors, dependency install, compilation output) and that partial logs are returned mid-build. It does not address log size limits, truncation, or pagination, which matters for a log-fetch tool.

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

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

Front-loaded purpose followed by return contents and a clearly flagged distinction; every paragraph has a function. Minor redundancy in restating the build-vs-runtime split twice.

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 takes on describing the return value and does so adequately, plus covers the partial-log case. It stops short of noting size limits or what an empty/failed-to-fetch response looks like.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including where release_id comes from. The description adds no additional meaning about the parameters, so the baseline 3 applies.

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

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

States a specific verb and resource ("Fetch build logs for a specific release") and immediately scopes it against the sibling deployado_get_logs. An agent can distinguish build logs from runtime logs without opening the schema.

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

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

Gives an explicit use case ("diagnose why a build failed") and an explicit exclusion with the named alternative ("For runtime logs of a running app, use deployado_get_logs instead"). The in-progress case is also covered.

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

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

Annotations already declare readOnlyHint/idempotentHint, so safety is covered; the description adds the meaningful behavioral fact that the response exposes connection credentials — a sensitive-data disclosure an agent should know before echoing output. It stops short of saying whether credentials are long-lived or secrets should be handled carefully.

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

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

One front-loaded sentence that states the resource and the most important content of the response. No filler, though slightly terse given the sensitivity of the returned data.

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 must carry return-shape information; it only lists 'connection URL and credentials' without indicating what other fields come back (host, port, name, engine) or the credential structure. Adequate to call correctly, but thin for interpreting the result.

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% ('Database ID (UUID)'), so the schema fully documents the single parameter. The description adds nothing about identifier format or lookup behavior; baseline 3 applies.

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

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

Names a specific verb ('Get detailed information') and resource ('a database'), and clarifies the payload (connection URL and credentials) so it is distinguishable from deployado_list_databases. It does not explicitly name siblings, but the single-resource fetch is clear.

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

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

Usage is only implied: fetch details for one database by ID. There is no explicit guidance on when to call this versus deployado_list_databases or deployado_connect_database, nor any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety behavior is fully covered by structured data. The description adds value by disclosing that the payload includes deployment phases and error details, but says nothing about failure modes (e.g., behavior for an unknown deployment_id) or response size.

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

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

A single front-loaded sentence with no filler, and the scope plus return contents come first. It is efficient, though slightly more could have been said to route between sibling tools without hurting brevity.

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?

There is no output schema, so the description is the only hint at return shape, and it gives just a brief sketch (phases, error details). For a simple two-UUID read tool this is adequate but leaves the agent guessing about what fields to expect and how to obtain the deployment_id in the first place.

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 both parameters (app_id, deployment_id) are documented as UUIDs in the schema, so the schema carries the load. The description adds no format or relationship detail beyond what is already structured — baseline 3 applies.

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

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

Clear specific verb (get) and resource (a specific deployment), and it names the returned contents ('phases and error details'), which separates it from list_deployments or get_logs. It stops short of explicitly distinguishing itself from close siblings like deployado_current_deployment or deployado_get_release.

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 word 'specific' implies a known deployment_id is required rather than fetching the latest, which is the main usage distinction. However, no sibling is named and there is no explicit guidance such as 'use current_deployment for the active one' or 'use list_deployments to find an ID', so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive and closed-world, so the safety profile is covered. The description adds real semantic context: logs are container-level runtime/application output, not build output. It stays silent on what happens if the app isn't running or how 'recent' is bounded.

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 purpose and followed immediately by the disambiguation. No filler or restated title text.

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 3-parameter read-only tool with full schema coverage and complete annotations, the description covers purpose and sibling routing adequately. Since there is no output schema, the absence of any hint about return shape or truncation behavior is a small remaining 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?

Schema description coverage is 100%, so lines, timestamps, and app_id are all documented in the schema. The description adds no syntax or constraint detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb + resource (fetch recent runtime logs) and scopes it precisely to 'a running app's container'. The explicit contrast with build logs lets an agent distinguish it from deployado_get_build_logs without opening either schema.

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

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

Gives an explicit when-not ('NOT build logs') plus the concrete alternative (deployado_get_build_logs) and the scenario that selects it ('why a deploy failed'). It does not address the other log-adjacent sibling deployado_release_logs, so the routing guidance is strong but not exhaustive.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds little beyond identifying the operation and does not describe return behavior, permissions, or not-found handling, but it does not contradict 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 definition is a single front-loaded sentence with no filler or repetition. Every word contributes to identifying the operation and scope.

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 one-parameter getter with rich annotations and full schema coverage, the description is minimally sufficient to invoke the tool. However, there is no output schema, and 'detailed information' does not indicate what project fields or response shape the agent should 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 description coverage is 100% and the single project_id parameter is already documented as a UUID in the schema. The description does not add format, example, or validation detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Get detailed information about a specific project.' It distinguishes a single-project lookup from list operations like deployado_list_projects, but does not explicitly name siblings or clarify how it differs from related getters such as deployado_get_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?

Usage is only implied: 'a specific project' suggests this is for retrieving one project by ID, but the description gives no explicit when-to-use guidance, no alternatives, and no exclusions compared with list_projects or other project-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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns build status, commit info, and error details—useful context given no output schema—but does not disclose additional behavioral traits like permissions or rate limits. A 3 is appropriate given the annotation coverage.

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 tightly written sentences, with the purpose front-loaded and a direct usage scenario following. Every sentence earns its place 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?

No output schema exists, but the description compensates by naming key return fields (build status, commit info, error details). For a simple get-by-ID read operation with full annotation coverage, this is sufficiently complete, though minor details about error detail structure or response format are absent.

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

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

Schema description coverage is 100%, with both app_id and release_id fully documented. The description adds no parameter-level meaning beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb ('Get') and resource ('release'), and enumerates the returned fields (build status, commit info, error details). It distinguishes itself from list_releases by emphasizing a 'specific release', but does not explicitly name alternatives like get_build_logs or release_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 one clear use case: checking build success or failure after triggering a deploy. However, it gives no guidance on when to use this tool versus siblings such as deployado_get_build_logs, deployado_release_logs, or deployado_get_deployment.

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, so the safety profile is covered. The description adds useful return-content detail (agent version, OS, architecture, Docker version) that is not in the annotations, though it omits error behavior and permission requirements.

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

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

A single sentence with zero waste, front-loading the core action and listing the most relevant returned fields. It is appropriately sized for a simple one-parameter read tool.

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 tool with one fully documented parameter and rich annotations, the description is largely complete. It covers what is returned, though it could mention invalid-ID or not-found behavior and does not explicitly route against deployado_list_servers.

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

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

Schema description coverage is 100%, so the sole parameter server_id is already documented as a UUID in the schema. The description adds no additional parameter meaning or format guidance beyond what the schema provides, which is the baseline expectation.

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

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

States a specific verb and resource: 'Get detailed information about a specific server.' The word 'specific' implies retrieval by ID rather than listing, which helps distinguish it from deployado_list_servers, though no sibling is named explicitly.

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

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

Usage is implied: call this when you already have a server ID and need its details. However, there is no explicit when-to-use guidance, no mention of when to use deployado_list_servers instead, and no prerequisites or exclusions.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere; the description adds none of the extra context that would earn credit, such as the kind of service records returned or their resolution format. Because there is no output schema, the description's failure to describe what 'detailed information' actually contains leaves a real gap, and it contributes nothing beyond the structured fields.

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

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

It is a single front-loaded sentence with no filler or repetition. The sentence is short but does not waste any words, though it borders on under-specification rather than true economy.

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?

As a simple read-only, single-parameter, idempotent lookup, the annotations and the schema cover most of what an agent needs. Without an output schema, it is more important to know what 'detailed information' returns, and the description does not supply that, so it is only minimally 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 coverage is 100% for the single service_id parameter, and the schema documents it as a UUID. The description adds no additional meaning, such as where to obtain the ID, 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 names a specific verb ('Get detailed information') and a specific resource ('a specific installed service'), which is enough to separate it from list_services or install_service. However, it never names a sibling, so the differentiation is inferred from the words 'specific' and 'installed' rather than stated.

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 never states when to use this tool instead of deployado_list_services or the start, stop, and restart siblings, and it gives no prerequisites, such as that you first need a service_id from the list endpoint. The only hint of context is the word 'specific', which the agent has to interpret on its own.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond restating that it installs from a template — no mention of provisioning side effects, whether the service starts immediately, expected failure modes, or that non-idempotent repeats create duplicates.

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

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

One tight sentence with the action and source front-loaded and no filler. It is efficient, but the brevity edges toward under-specification rather than ideal conciseness.

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?

This is a mutating provisioning tool with a free-form nested 'config' object and no output schema, so the description should say what gets created, what config accepts, and what the caller gets back (e.g., a service ID). All of that is absent, leaving the agent to infer the post-call state.

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%: name, template_id, memory_mb and the open-ended config object are all documented inline, including a pointer to list_service_templates. The description adds no extra semantics, which is the baseline 3 case when the schema does the heavy lifting.

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

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

Specific verb ('Install') plus resource ('new service') plus source ('marketplace template') tells the agent this provisions a service instance rather than starting an existing one. It is distinguishable from start_service in principle, though it never names the sibling.

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

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

No when-to-use or when-not guidance, and no mention of alternatives such as deploy_blueprint or create_app, which are adjacent provisioning paths. The only routing hint (list_service_templates) lives in the schema, not the description.

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, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context of its own — no indication of ordering, result size, pagination, or whether apps from all projects are returned by default.

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

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

Two short sentences, zero waste, with the core action front-loaded and the optional filter trailing as a qualifier. Nothing repeats or pads.

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 one-parameter read-only listing tool with full annotations and a fully documented schema, the description covers the essentials. It is nonetheless thin on what the agent gets back (a flat list? per-project grouping? pagination?) — acceptable given no output schema, but not 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% and the single parameter is documented as 'Filter by project ID', so the baseline is 3. The description mirrors that phrasing but does add the useful implication that omitting it returns every app in the account; it contributes nothing on the expected ID format or filter behavior.

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

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

States a specific verb and resource ('List all apps') and scopes it to the account, which cleanly separates it from siblings like deployado_get_app, deployado_create_app, and deployado_list_deployments. It does not explicitly name a sibling it is not, so it stops short of a 5.

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

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

The only usage signal is 'Optionally filter by project ID' — there is no statement of when to reach for this versus deployado_get_app (single app) or deployado_list_projects, and no preconditions or exclusions. An agent can infer the obvious use case, but nothing is spelled out.

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 and openWorldHint=false, so the safety profile is fully covered. The description adds only the account-scoping detail; it says nothing about result ordering, empty-list behavior, or that the returned targets feed run_backup/restore_backup.

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

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

A single front-loaded sentence with no filler. The resource and scope land in the first few words, which is exactly what an agent scanning candidates needs.

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 no-parameter read tool with annotations covering safety, the description is minimally sufficient. It is incomplete in that it does not say what the targets are used for downstream (backups/restores) or how they relate to the create/get/run backup siblings in the same namespace.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description does not promise any filtering options, which matches the empty schema and avoids misleading the agent.

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

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

States a specific verb and resource (list backup targets) and scopes it to 'configured for your account', which distinguishes it from deployado_get_backup_target. However, it never names or contrasts with the obvious sibling that fetches a single target, so a reader must infer the relationship.

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

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

Usage is implied by the name and the word 'all' — this is the enumerate-everything variant — but the description gives no explicit when-to-use / when-not-to-use guidance and does not point to deployado_get_backup_target for details or deployado_create_backup_target for adding one.

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, and closed-world scope, so the safety profile is covered. The description adds only the per-app scoping note; it says nothing about ordering, pagination, or what fields each cron job returns.

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

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

A single short sentence with the scope stated immediately and no filler. Nothing could be removed without losing meaning.

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 one-parameter read-only list tool whose annotations cover safety and whose schema fully documents the argument, the description is nearly sufficient. Only the return shape (and that there is no output schema) is left implicit.

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

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

Schema coverage is 100%, so app_id is already documented as a UUID. The description's 'for an app' phrasing reinforces the parameter's role but adds no format or constraint detail beyond the schema. Baseline 3 applies.

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

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

Uses a specific verb (List) and resource (cron jobs) and states the scope (for an app). It's distinguishable from create/update/delete/run cron job siblings by name, but the description doesn't explicitly contrast with them.

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

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

Usage is implied: use it to inspect existing cron jobs before updating or deleting, but the description never says when to use it versus deployado_create_cron_job or deployado_run_cron_job. No prerequisites or exclusions are stated.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior. The description adds that the listing is over managed PostgreSQL databases and that filters are optional, but it does not mention pagination, return format, or ordering.

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 short sentences, front-loaded with the core action. The filter sentence is useful but slightly redundant with the schema, keeping it from a perfect score.

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 list tool with complete parameter descriptions and rich annotations, the description covers the essential scope and filtering behavior. It lacks return-shape detail, but no output schema exists, so a minor gap remains.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description only restates that project and status filtering are optional, adding no syntax, format, or semantic detail 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 uses a specific verb and resource: 'List all managed PostgreSQL databases'. It is clearly distinguishable from siblings like get_database or create_database, though it does not explicitly contrast itself with any particular sibling.

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 states that filtering by project or status is optional, which implies the main use case. However, it gives no explicit guidance on when to use this tool versus get_database or project-scoped listing 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, so the safety profile is fully covered elsewhere. The description's only extra contribution is noting the returned fields (status, version, timing), which is modest but genuine value; it says nothing about ordering, pagination, or empty results.

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

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

A single short sentence with zero filler, and the scope ('for an app') and output fields are front-loaded. It could have used one more clause for sibling differentiation without becoming bloated, but there is no waste as written.

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?

This is a simple two-parameter read-only list operation with full schema coverage, complete annotations, and no output schema requirement. The description plus structured fields give an agent everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%: app_id (UUID) and limit (default 10, max 50) are both fully documented in the schema. The description adds nothing about limit behavior or result ordering/capping, so the baseline of 3 applies.

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

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

States a specific verb ('List') and resource ('deployments') with the scope narrowed to a single app, and names the fields surfaced (status, version, timing). It is clear on its own, but it does not explicitly distinguish itself from close siblings like deployado_get_deployment or deployado_current_deployment.

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 word 'recent' and the required app_id imply the intended use case (browse a history for one app), but the description never states when to prefer this over get_deployment, current_deployment, or list_releases. No exclusions or prerequisites are given; usage must be inferred from the sibling name pattern.

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, and openWorldHint=false, so the safety profile is well covered. The description adds useful behavioral detail by noting that the auto-generated subdomain is included in the result. However, it does not describe ordering, pagination, or authentication requirements, which keeps it at a moderate level.

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 compact sentence with zero wasted words. The key scope information is front-loaded and easy to parse.

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 list tool with one fully documented parameter and rich annotations, the description covers the essential purpose and one important scope detail. Because there is no output schema, it could say more about the return shape, but for this complexity level 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%, and the single parameter app_id is fully documented in the schema. The description implies that listing is scoped to an app but adds no format or semantic detail beyond what the schema already provides. Baseline 3 is appropriate when the schema carries 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 states a specific verb and resource: listing all custom domains for an app. It also clarifies that the auto-generated subdomain is included, which is useful scope. It does not explicitly distinguish itself from sibling domain tools such as add_domain or verify_domains, so it falls short of a 5.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention sibling tools like add_domain, remove_domain, set_primary_domain, or verify_domains, nor does it state when this tool should not be used. Usage is only weakly implied by the verb 'List'.

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. The description adds valuable context beyond that: 'Values of secret variables may be masked,' which tells the agent output may be incomplete for secrets.

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

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

Two short front-loaded sentences with zero waste. The scope statement comes first and the masking caveat second.

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 single-param tool, annotations plus schema cover safety and inputs, and the masking note covers the key output caveat. No output schema exists, but the description doesn't need to fully describe return shape for a straightforward list.

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

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

Schema coverage is 100% with a single well-documented app_id (UUID) param. The description adds only that variables are scoped to an app, which the schema already conveys, so baseline 3 applies.

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

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

Clear verb+resource: 'List all environment variables for an app.' An agent can distinguish it from set_env/delete_env by the 'list' verb. It lacks explicit sibling differentiation, but the operation is 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 scope 'for an app' implies needing an app_id, but there is no explicit when-to-use guidance versus alternatives like set_env or get_app, and no exclusions. Usage is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only the account-scoping context ('all projects in your account'); it says nothing about pagination, result ordering, or volume limits beyond 'all'.

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

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

A single front-loaded sentence with no filler or repetition. It is efficient, though it is arguably terse enough that brevity shades into under-specification.

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 no-param, non-destructive read with full annotation coverage, this is minimally adequate. It omits what fields each project record contains and whether results are paginated or capped, which matters for a 'list all' tool with no output schema to document the return shape.

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 has zero parameters, so there is no parameter semantics burden on the description. Baseline 4 applies; nothing in the description misrepresents the empty schema.

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

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

States a specific verb and resource ('List all projects') with a clear scope ('in your Deployado account'). It does not, however, differentiate itself from adjacent list tools such as deployado_list_apps, deployado_list_servers, or deployado_get_project, leaving the agent to infer the project-vs-app distinction from names alone.

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

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

There is no when-to-use guidance and no named alternative. The description never says to prefer deployado_get_project for a single project or how this differs from deployado_list_apps, so the agent gets no routing help.

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 it a safe, idempotent, closed-world read, and the description complements this by enumerating the release status values (queued, pending, building, ready, failed), which is real behavioral detail the annotations cannot convey. Since there is no output schema, this return-value context is the main place that information can live. It does not state ordering or whether all releases or only recent ones are returned.

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

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

Three short sentences, front-loaded with purpose, then the status vocabulary, then a routing pointer. Every sentence carries information an agent needs and nothing is padded.

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

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

With no output schema, the description usefully covers what comes back (versions, build status and its possible values). What it omits is the sort/recency behavior of the listing and what happens with an invalid app_id, which matter for a paged listing tool.

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

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

Schema description coverage is 100% and both parameters (app_id UUID, limit default 10 / max 50) are documented there, so the baseline of 3 applies. The description adds nothing about app_id format or limit behavior beyond what the schema already says; the release_id mention refers to a sibling tool's parameter.

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

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

States a specific verb and resource, "List available releases for an app," plus the fields returned (version history, build status). It does not explicitly distinguish itself from siblings like deployado_get_release or deployado_list_deployments, which an agent could easily confuse with this tool.

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 final sentence gives explicit routing: use deployado_get_build_logs with a release_id to see build output, which cleanly separates this listing tool from log retrieval. It offers no guidance on when to prefer deployado_get_release or deployado_list_deployments, so the sibling disambiguation is incomplete.

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, and openWorldHint=false, so the safety profile is fully covered. The description adds useful content about what the result includes (status, CPU/memory/disk metrics), but says nothing about pagination, result size, or authorization requirements.

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

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

A single tight sentence that leads with the verb and resource and then the returned fields. Every clause earns its place with no filler.

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

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

For a no-parameter list tool with no output schema, the description tells the agent what it will get back (status and resource metrics), which is enough to call it correctly. Only minor gaps remain around result size and whether filtering exists elsewhere.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly implies an unfiltered full-listing behavior that matches the empty schema.

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

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

States a specific verb ('List') and resource ('servers') plus the payload (status and CPU/memory/disk metrics). It is clearly the collection counterpart to the sibling deployado_get_server, so an agent can distinguish them from name and description alone.

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

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

Usage is implied: this is the way to enumerate all servers. However, it never states when to prefer deployado_get_server (single-server detail) over this, nor any precondition or scope constraint (e.g., all servers vs. filtered set). No explicit alternatives are named.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world behavior, so the safety profile is covered. The description adds only the account scoping and the fact that only installed services are returned; it says nothing about result size, ordering, or pagination.

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

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

A single front-loaded sentence with no filler or repetition. Its only weakness is that it uses so few words that important context is omitted.

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 list tool with rich annotations and a fully documented single parameter, the description is adequate. It remains thin on what the agent gets back and whether results are paginated, which matters for a list operation with no output schema.

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

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

Schema description coverage is 100%, and the optional status filter is fully documented in the schema with allowed values. The description adds no parameter detail beyond that, so the baseline of 3 applies.

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

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

The description gives a specific verb and resource ('List all installed services') and adds a scope of 'for your account', which distinguishes it from the service-template lister. It does not explicitly contrast with sibling list tools such as deployado_list_apps or deployado_list_servers.

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

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

There is no explicit guidance about when to use this tool, when to prefer deployado_get_service, or how it relates to the other list operations. Usage is only implied by the verb 'List'.

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, and openWorldHint=false, so safety and side-effect behavior are fully covered. The description adds only domain framing (databases, caches, monitoring tools); it says nothing about result ordering, pagination, or size of the catalog.

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

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

A single front-loaded sentence with no filler; the parenthetical examples earn their place by illustrating template scope. The trailing 'etc.' is slightly loose for a definition that could enumerate the catalog's categories precisely.

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 zero-required-parameter, read-only list tool with full annotation coverage and a fully described schema, the description is adequate but thin. It omits the return shape (since no output schema exists) and the link to deployado_install_service, which is the main reason an agent would call it.

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

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

Schema coverage is 100%, so the single optional 'category' parameter is already documented with an example value list. The description's examples ('databases, caches, monitoring tools') loosely echo those category values but add no new guidance, such as case sensitivity or what happens when omitted. 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+resource combination ('Browse available service templates') and scopes it to 'the Deployado marketplace', which is clear. It does not explicitly differentiate from the closely-named sibling deployado_list_services (installed services) or deployado_install_service (which presumably consumes these templates), so the sibling distinction is only implicit.

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 word 'Browse' and 'available' imply this is a discovery step preceding deployado_install_service, but no alternative or trigger condition is stated. An agent must infer the workflow (list templates -> install_service) rather than being routed to it.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower; the description still adds genuine context beyond them — it works for both in-progress and finished builds, and returns status/timing metadata alongside the logs. It stops short of stating truncation behavior or size limits, but the useful traits are disclosed.

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

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

Three tight sentences, front-loaded with the core action, then behavior, then usage. No filler or repetition. A fifth point would require tightening the mild overlap between the 'works for both' and 'returns the full logs' 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?

With no output schema, the description carries the return-value burden and does so ('full logs plus status/timing metadata'). Combined with the fully-specified input schema and annotations, an agent has nearly everything needed — only the sibling overlap with `get_build_logs` is unaddressed.

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

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

Schema coverage is 100%, so both parameters are fully documented and the baseline is 3. The description adds only a loose hint about where release IDs come from (and slightly diverges from the schema, which points at `list_releases` rather than `deployado deploy` output).

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: 'Fetch the docker build transcript for a release.' An agent knows exactly what it retrieves. However, it never distinguishes itself from the near-identical sibling `deployado_get_build_logs` (and `deployado_get_logs`), which leaves real ambiguity for selection.

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?

'Use this when investigating a build failure' gives a clear trigger context, and provenance of the release ID is spelled out. But no when-NOT-to-use guidance and no mention of the competing `get_build_logs` / `get_logs` siblings, which is the main thing an agent would need resolved here.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on irreversibility, DNS/certificate cleanup side effects, or whether removing a primary domain is blocked — so it earns little credit over structured data.

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

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

A single front-loaded sentence with zero waste. It is terse but does not pad or bury the purpose, though it borders on under-specification for a destructive operation.

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 and full annotation coverage, the core is adequate for a simple two-parameter mutation. However, for a destructive domain operation an agent would benefit from knowing the effect on DNS records, primary-domain status, or attached certificates, which is absent.

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

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

Schema coverage is 100% and both parameters (app_id, domain_id as UUIDs) are documented in the schema, so the baseline is 3. The description adds no further meaning about the identifiers or their relationships.

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 a custom domain from an app'), which is unambiguous about what the tool does. It does not, however, distinguish itself from close siblings like set_primary_domain or verify_domains, leaving the agent to infer the boundary.

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

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

There is no guidance on when to use this versus add_domain, set_primary_domain, or verify_domains, and no stated preconditions (e.g., whether the domain must first be detached or whether it is the primary domain). The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety envelope is known. The description adds nothing beyond that: it does not warn of service interruption, explain what happens to in-flight requests, or clarify the non-idempotent behavior the annotation flags.

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 single sentence is front-loaded and free of filler, but it is under-specified rather than genuinely concise: for a mutating operation with no output schema, one sentence leaves the agent without operational context that could have been added in a few 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 service-restart mutation with no output schema, the description should convey at minimum the effect on the running service and how to confirm success (e.g., check logs or service status). None of that is present, so the definition is thin for a state-changing tool despite complete parameter coverage.

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

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

Schema coverage is 100% with a single required service_id documented as a UUID in the schema itself. The description contributes no additional meaning (e.g., accepted formats, whether the service must be in a particular state), so baseline 3 applies.

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

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

The description states a specific verb and resource ('Restart a service'), which is unambiguous and clearly a mutation rather than a read. It does not, however, distinguish itself from the sibling operations start_service and stop_service, leaving the boundary between those three implicit in the verb alone.

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

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

There is no guidance on when to restart versus stop/start a service or redeploy, and no mention of prerequisites such as a healthy deployment or expected downtime. The agent must infer the usage scenario entirely from the verb.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description earns credit for adding the concrete consequence — the target database is overwritten — which tells the agent what data is lost, not just that the call is destructive. No mention of irreversibility, permissions, or async behavior, so it stops short of a 5.

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

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

Two sentences, both load-bearing, with the action stated first and the risk immediately after. Nothing redundant with the name or title.

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

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

Adequate for a well-annotated tool with a fully documented schema, but it omits the return behavior (no output schema exists, so the description is the only source) and doesn't acknowledge that restoring to a different target via destination_target_id means a non-source database is what actually gets overwritten.

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 all four parameters including drop_first and destination_target_id are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline for full schema coverage.

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

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

Names a specific verb and resource ('Restore a database') and scopes it to a specific source ('from a specific backup run'). Unambiguous against sibling tools like deployado_run_backup or deployado_list_backup_targets, though no sibling is named explicitly as an alternative.

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

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

The description implies its use case (recovering a database from a backup run) and the overwrite warning gives the agent a reason to pause, but it never states prerequisites, when to prefer this over alternatives, or when not to call it. Usage is inferred rather than guided.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation/safety profile is covered. The description adds no further behavioral detail: it doesn't say whether rollback triggers a new deployment and restart, causes downtime, or what happens to the currently running release.

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

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

A single front-loaded sentence with no filler and no wasted clauses. It is efficient, though extremely terse for a destructive operation.

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, non-idempotent mutation with three parameters and no output schema, the description is too thin. It omits how to identify the target release (version vs release_id), side effects on the running app, and the absent idempotency caveat that a repeat call may roll back to a different state.

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 app_id/version/release_id are documented in the schema, and the phrase 'previous release version' loosely maps to the version field. However, the description never explains the relationship or precedence between 'version' and 'release_id', leaving a real ambiguity for the caller.

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

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

The description names a specific verb ('Rollback') and resource ('an app') plus the target ('a previous release version'), which cleanly separates it from deploy/create_app/deploy_blueprint siblings. It stops short of explicitly contrasting with list_releases/get_release, which are the lookup tools an agent must use to find the target.

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

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

There is no guidance on when to prefer rollback over a fresh deploy, no prerequisite that the target release must exist, and no mention of constraints such as an in-flight deployment. The agent must infer all routing decisions.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered elsewhere. The description's only extra signal is 'immediate', and it says nothing about whether the call blocks or returns a job handle, how long a backup takes, or whether repeated calls queue duplicate backups (idempotentHint=false makes that a real question).

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

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

A single short sentence with verb and scope front-loaded and no filler. It is efficient, though its brevity is closer to sparseness than to well-packed density.

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 one required parameter, full schema coverage, annotations carrying the safety and idempotency profile, and no output schema to explain, the definition is close to sufficient. What is still missing is the operational context: whether the trigger is async, what the caller gets back, and how target_id is obtained.

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

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

Schema coverage is 100% and the single parameter is documented as a UUID-typed 'Backup target ID', so the schema does the heavy lifting. The phrase 'for a target' adds no format or sourcing detail beyond it, which makes the baseline 3 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 ('Trigger an immediate backup') plus the scope ('for a target'), which lets an agent separate it from deployado_list_backup_targets, create_backup_target, and restore_backup. It stops short of naming those siblings explicitly, so no credit for explicit differentiation.

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

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

There is no guidance on when to call this instead of creating a new target, restoring a backup, or letting a scheduled backup run. It also omits the prerequisite that target_id must come from list_backup_targets, forcing the agent to infer the workflow.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the agent knows this is a non-idempotent mutation that isn't destructive. The description adds the timing semantics ('run immediately'), which is genuinely valuable context, but says nothing about whether this produces a deployment/release, what it returns, or whether triggering is safe to repeat.

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

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

A single zero-waste sentence with the action front-loaded. Efficient, though brevity here comes partly at the cost of the missing return/effect 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?

For a two-parameter trigger tool with full schema coverage and useful annotations, the essentials are present. What's missing is the observable effect: whether it creates a release/deployment and what the caller gets back (no output schema exists to answer this).

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% (both app_id and cron_id documented as UUIDs), so the baseline is 3. The description adds no parameter-level detail such as whether IDs must belong to the same project or how to discover them.

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

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

States a specific verb (trigger/run) and resource (cron job) with the key qualifier 'immediately', which distinguishes it from scheduled execution and from sibling management tools like list_cron_jobs or update_cron_job. The purpose is unambiguous, though it does not explicitly name which sibling to prefer.

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?

'Manually trigger' implies the on-demand use case versus waiting for the schedule, which is useful implied guidance. However, there is no explicit when-to-use/when-not, no mention that the job must already exist, and no named alternative (e.g., create_cron_job for new jobs).

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

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

The annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety bar is lower. The description nonetheless adds genuinely useful behavior the annotations cannot express: values are merged with existing variables rather than replacing the map, and a redeploy may fire automatically as a side effect. It doesn't explain that overlapping keys are overwritten (which is why the tool is flagged destructive), so a small gap remains.

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

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

Three short sentences, zero filler, with the core action front-loaded and the merge behavior and redeploy side effect following in priority order. 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 with no output schema, the description covers the action, the merge semantics, and the redeploy side effect, which is most of what an agent needs. It omits the overwrite behavior on duplicate keys and gives no hint about the response, keeping it from a 5.

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

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

Schema coverage is 100%, and the schema fully documents both app_id (UUID) and the nested env key-value map with an example. The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a clear verb+resource phrase, 'Set or update environment variables for an app', which lets an agent distinguish this mutating tool from the sibling readers deployado_list_env and the destructive deployado_delete_env. It does not explicitly name those siblings, so it stops short of a 5.

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

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

'Merges with existing variables' implies this is the additive/update path rather than a replace or delete, giving implied usage. However, it never states when to prefer this over deployado_delete_env or when a redeploy must be done explicitly, leaving the agent to infer.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the mutation/idempotency profile is covered. The description adds the useful consequence that the primary domain drives redirects, but omits what happens to the previously primary domain (demoted? left in place?) and whether verification is required.

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

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

Two short sentences, front-loaded with the action, zero filler. The redirects sentence is the only one that could be questioned, but it does add behavioral context.

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 small two-parameter tool with full schema coverage, rich annotations and no output schema, the definition is adequate but not complete: it does not cover the previous-primary-domain side effect, preconditions, or return behavior, which an agent would want before mutating state.

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 both parameters (app_id, domain_id) are documented as UUIDs, so the baseline is 3. The description adds no further meaning about how the IDs are obtained or any cross-parameter 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?

States a specific verb and resource ('Set a domain as the primary domain for an app') and clarifies the effect ('used for redirects'). It is distinguishable from add_domain/remove_domain/list_domains by the 'primary' qualifier, though it never names those siblings explicitly.

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

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

The intent is implied by the name and the redirects note, but there is no explicit guidance on when to call this versus deployado_add_domain or deployado_verify_domains. No prerequisites are stated, such as whether the domain must already be added and verified before it can be promoted.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and repeat-call profile is carried by structured data. The description adds only the precondition that the target should be stopped; it doesn't say what happens if the service is already running, whether the call blocks until healthy, or whether it can fail on a transitioning state.

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

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

One short sentence, front-loaded with the verb and with no filler. It is efficient, though the brevity borders on under-specification rather than true tightness.

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

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

For a single-parameter action tool with rich annotations and a fully described schema, the description covers the essential action and precondition. No output schema exists, but the missing pieces (behavior on an already-running service, blocking semantics) are secondary for this complexity level.

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

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

There is a single parameter with 100% schema description coverage ('Service ID (UUID)'), so the schema already fully documents it. The description adds nothing about the identifier beyond the schema, making baseline 3 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+resource ('Start ... service') and adds the precondition 'stopped', so the action is unambiguous. It does not distinguish itself from sibling deployado_restart_service, which performs an overlapping operation, so it falls short of full sibling differentiation.

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?

'a stopped service' implies the usage condition (the service must currently be stopped), but the description never says when to prefer this over deployado_restart_service or deployado_stop_service, nor what to do if the service is already running. Usage is only inferable.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered by structured data. The description adds almost nothing beyond what annotations provide – no mention of downtime, whether the stop is graceful or forced, or what happens if the service is already stopped. Given the lower bar when annotations are rich, this is thin but not incorrect.

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

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

A single front-loaded sentence with no filler. It is efficient, though efficiency here comes at the cost of under-specification rather than tight, complete phrasing.

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

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

For a destructive, non-idempotent operation with no output schema, an agent would want to know effects (downtime, impact on deployments, reversibility via start_service) and error behavior. None of that is present, leaving the definition adequate only in the narrowest sense.

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 single parameter has 100% schema description coverage ('Service ID (UUID)'), so the baseline of 3 applies. The description adds no additional meaning about the identifier or its resolution.

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 ('Stop a running service') and is clearly distinct from sibling operations like start_service or restart_service. It lacks any detail about scope (what a 'service' is here, what stopping affects), so it stops short of fully differentiating behavior.

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

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

No guidance on when to use this versus restart_service or rollback, and no stated prerequisites such as the service needing to be running. The only implicit cue is the word 'running', which hints at a precondition but is not stated as one.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say whether omitted fields are left unchanged, whether changes trigger a redeploy or restart, or which settings are irreversible.

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

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

A single front-loaded sentence with no waste, but it is under-specified rather than concise. The brevity leaves critical gaps an agent needs filled.

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?

This is a destructive 11-parameter mutation with no output schema and no annotations beyond hints. The description says nothing about partial-update semantics, side effects like redeploys, or the response, so it is not complete enough for the agent to call it safely.

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

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

Schema description coverage is 100%, so every parameter including the deploy_gate and auto_rollback semantics is already documented in the schema. The description adds no parameter meaning, which is acceptable at baseline 3 given full schema coverage.

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

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

"Update an existing app's configuration" states a clear verb and resource, which separates it from create_app/delete_app by name. But "configuration" is vague about the 11 fields actually editable (name, port, dockerfile path, auto-deploy, rollback window), and it does not distinguish this from deployado_update_project or deployado_deploy.

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

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

There is no guidance on when to use this instead of deployado_deploy, deployado_rollback, or deployado_update_project, and no mention of prerequisites. The agent must infer everything from the tool name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds nothing beyond that — no mention of what happens to fields not supplied, whether the cron schedule is re-validated, or permission requirements.

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

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

A single front-loaded sentence with zero padding or redundancy. It is efficiently sized, though that efficiency comes at the cost of substance rather than being paired with 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 an 8-parameter destructive mutation tool with no output schema and non-idempotent semantics, the description should at least clarify partial-update behavior (whether omitted fields are preserved or reset) and what the response contains. None of that is present.

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%, with each of the 8 properties documented and the status enum enumerated, so the schema carries the parameter burden. The description adds no semantics of its own, which is the baseline 3 case.

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: update an existing cron job. An agent can identify the operation immediately, though the description offers no explicit differentiation from siblings like deployado_create_cron_job or deployado_delete_cron_job beyond the name itself.

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

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

No guidance on when to use this versus create_cron_job, delete_cron_job, or run_cron_job, and no prerequisites (e.g., the job must already exist, app_id must match). Usage is only implied by the tool name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds nothing beyond that: no note that omitted fields are left untouched, no mention that changing repository_url or default_branch affects future deployments, no confirmation of mutation scope.

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

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

One short, front-loaded sentence with no filler. It is efficient, though its brevity comes at the cost of the partial-update semantics being unstated.

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, non-idempotent mutation with no output schema, the description should at minimum explain partial-update behavior and the impact of repository_url/default_branch changes. Neither is covered, leaving an agent to infer the mutation's blast radius.

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 each of the five parameters is already documented in the schema; the baseline of 3 applies. The description names two of the five (name, description) and hand-waves the rest as 'other settings', adding no meaning beyond the schema.

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

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

Specific verb+resource ('Update a project's ... settings') that clearly distinguishes it from delete_project, get_project, update_app and other siblings. However, 'or other settings' is a vague catch-all that omits the two most consequential fields actually in the schema (default_branch, repository_url).

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

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

No guidance on when to use this versus create_project, delete_project, or update_app. It also never states the key usage fact implied by the schema: that only project_id is required and all other fields are optional, so callers can perform a partial update.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description contributes genuine extra context: no deployment occurs and the caller gets back a preview of what would be created, which is exactly what an agent needs to know before trusting a dry run. A 4 because it adds value beyond annotations but says nothing about error/failure semantics.

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

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

Two short sentences, front-loaded with the action and the crucial 'without deploying' constraint, followed by the return value. No filler.

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

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

For a single-parameter, non-destructive validation tool with no output schema, the description covers what it does, that it is safe, and roughly what comes back (validation results plus a creation preview). Slightly incomplete in not describing failure behavior or what the preview contains.

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

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

Only one parameter and schema coverage is 100%, so the schema fully documents 'content'. The description repeats the format (YAML blueprint) without adding syntax, sizing, or example guidance — baseline 3 is appropriate.

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

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

States a specific verb+resource (validate a blueprint YAML) and adds a key qualifier, 'without deploying it,' which implicitly distinguishes it from deployado_deploy_blueprint. It stops short of naming the sibling explicitly, but the intent is 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?

'Without deploying it' implies this is the dry-run/pre-flight step before deploy_blueprint, which is useful, but the description never states when to prefer this over deploying directly or what to do with a failed validation. Usage is implied rather than prescribed.

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 idempotent, non-destructive, open-world behavior, so the safety profile is largely covered. The description adds that results are reported per domain, but says nothing about whether the check is synchronous, what happens on partial DNS propagation, or whether any state is written despite the read-like verb — a meaningful gap given readOnlyHint is 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?

Two short sentences, zero filler, with the action front-loaded and the return behavior relegated to a compact second clause. Nothing needs trimming.

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 one-parameter tool with no output schema, the description covers the essential: what it checks, on what scope, and that it returns per-domain status. It could say more about what the status values mean or how to act on a failing domain, but nothing an agent needs to invoke it correctly is missing.

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

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

Only one parameter (app_id) with 100% schema description coverage, so the schema already carries the semantics and baseline 3 applies. The description reinforces scope ("all domains of an app") but adds no format or constraint detail beyond the schema.

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

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

States a specific verb and resource ("Verify DNS configuration for all domains of an app") and scopes it to all domains rather than one. An agent can distinguish it from list_domains or add_domain without opening the schema, though the description never names those siblings explicitly to sharpen the contrast.

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

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

Usage is only implied: the natural read is "call this after adding or changing a domain," but the description never says when to invoke it or when another tool (list_domains, add_domain, set_primary_domain) is the better choice. No prerequisites or failure conditions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds that the payload includes API token information, which is behaviorally salient, but it does not say whether the token is masked or returned in full — a meaningful omission for a read that touches credentials.

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

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

Two sentences, no waste, with the payload contents front-loaded before the diagnostic use case. Every clause earns its place and nothing is buried.

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

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

With no output schema, the description carries the burden of describing return values, and it does so at a high level (account, user, token). It is nearly complete for a zero-parameter identity probe; only the sensitivity/format of the token field is left unstated.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. It correctly avoids inventing options or filters that the empty schema does not support.

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

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

The description uses a specific verb+resource pair ('Show current account, user, and API token information') that no sibling duplicates — the other 50+ deployado tools operate on apps, deployments, domains, databases, and so on, none on identity. It is clear without opening the schema, though it doesn't explicitly contrast with a nearby diagnostic tool like deployado_doctor.

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?

'Useful to verify authentication is working' supplies a concrete when-to-use condition that an agent can act on. It stops short of naming an alternative (e.g., deployado_doctor for broader health checks) or stating when not to call it, so it is clear context rather than full routing guidance.

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