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

Annotations already declare this is a non-destructive, idempotent, open-world write. The description adds real behavioral context beyond them: the key must belong to the invited email's account, and the required scope (workspaces:invites) is disclosed. It doesn't say what happens on an invalid or expired token, keeping it just below top marks.

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 tight sentences plus a scope tag, with the core action leading. The email caveat is front-loaded rather than buried at the end. Little 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?

For a single-parameter tool with annotations carrying the safety profile and no output schema, the description covers what an agent needs: action, effect, account constraint, and scope. Only the failure/expiry behavior is left implicit, which is a minor 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?

With 100% schema description coverage, the schema already documents the single token parameter including 'the final part of the link'. The description adds no further parameter 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 ('Accepts') plus resource ('invite') and effect ('joins the workspace with the account that owns the key'), which clearly defines the action. It doesn't reference the sibling invite tools (preview_workspace_invite, decline_workspace_invite), so sibling differentiation relies on the name 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?

The email-account constraint gives useful context, but there is no explicit 'use this to join' vs 'use decline_workspace_invite to reject' or 'preview first to inspect the invite' guidance. Usage is only implied. 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 establish mutation, idempotency, non-destructiveness, and open-world behavior. The description adds the required permission scope (workspaces:write), which is useful auth context, but does not explain side effects such as what happens to prior workspace membership or whether the app must already exist.

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 clauses, front-loaded with the action and resource, then permission scope. There is 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?

The scope tag plus annotations make the operation mostly callable, but with only 50% schema coverage and no output schema, the description should say more about app_id and the effect on any existing workspace association. It is minimally adequate for a simple mutation but leaves clear 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?

Schema coverage is only 50%; the schema documents 'id' as Workspace ID but leaves 'app_id' undocumented. The description contributes no parameter meaning, so the agent gets no help understanding app_id or required formats beyond the bare schema.

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

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

Names a specific verb (Moves) and resource (application into workspace), and is distinguishable from remove_app_from_workspace. However, 'Moves' is slightly ambiguous versus the tool name add_app_to_workspace and does not explicitly clarify whether it removes the app from a prior workspace.

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 no explicit when-to-use guidance, no prerequisites beyond a scope tag, and no comparison to siblings such as remove_app_from_workspace or add_database_to_workspace. The agent must infer usage 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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the required scope (workspaces:write), which is useful auth context, but says nothing about side effects on the database or apps, or about failure when the database is already in a workspace.

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 terse sentences with the action front-loaded and the scope qualifier appended. No wasted words, though the scope parenthetical could have been spent on more useful usage detail.

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 2-parameter mutation with no output schema and clear annotations, the basics are present. But an agent would still lack guidance on preconditions (database state, permissions beyond scope) and on the expected effect, leaving the definition minimally adequate.

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

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

Schema coverage is only 50%: 'id' is documented as the Workspace ID but 'database_id' has no schema description. The tool description clarifies neither parameter, so it does not compensate for the coverage gap by explaining what database_id refers to.

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 ('Moves') and resource ('a database into the workspace'), which is clearly directionally distinct from the sibling remove_database_from_workspace. However, it never names that sibling or clarifies the 'into' versus 'out of' pairing explicitly, so it stops short of full 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 when-to-use guidance, no prerequisites (e.g. database must exist, must not already be in the workspace), and no mention of the obvious alternative remove_database_from_workspace. The usage is only implied by 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?

Beyond the annotations, the description discloses that no redeploy is needed, that a www/root companion is created by default and does not count toward the plan limit, that DNS records must be obtained via `get_domain_dns`, and it lists specific possible errors and the required 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?

The description is front-loaded with the primary action and default behavior, and every sentence carries operational value. The long inline list of error codes is useful but makes the paragraph dense; a more structured layout would read more easily.

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 mutation tool with no output schema, the description covers purpose, defaults, DNS follow-up, important parameter interactions, error cases, and authorization scope. It leaves `workspace_id` unexplained and does not describe the return value, which are modest remaining 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?

Schema coverage is 88%, so the schema already documents most parameters. The description still adds useful semantics: `redirect_to` must be another domain of the same application and works with `redirect_status`, `path_prefix` is prepended to every request, and `port` is the application port. It does not explain `workspace_id`.

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: 'Adds a custom domain to the application.' It also clarifies the no-redeploy effect and the automatic www/root companion, making the operation distinct from update_domain, remove_domain, and list_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?

It gives clear usage context and a concrete next step: 'Then call `get_domain_dns` for the records to create at the DNS provider.' It does not explicitly name when to choose add_domain versus update_domain or remove_domain, so the 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?

Annotations already signal mutation (readOnlyHint=false), non-destructiveness (destructiveHint=false), and idempotency (idempotentHint=true), so the bar is lower. The description adds the 'account:write' scope and confirms the put-into-folder action, which is consistent with the annotations and provides some extra context, but it does not explain what happens on duplicate adds or other behavioral nuances.

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, front-loaded sentence that communicates the core action without filler. The parenthetical scope note adds value, but the overall brevity leaves room for parameter detail without becoming bloated.

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 4-parameter mutation tool with no output schema, the description is too thin. It does not clarify whether the folder_id must reference a personal folder, whether the resource must already exist, what happens on duplicate placement, or what the response will contain, leaving meaningful gaps for an agent to call 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 description coverage is only 25%, so the description should compensate, but it does not. It mentions application/database types, matching resource_type, but does not clarify resource_id semantics, folder_id ownership, or the meaning of the optional position parameter 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?

The description uses a clear verb ('Puts') with a specific resource ('an application or database') and target context ('personal folder'), so an agent can tell what it does. It distinguishes reasonably from sibling add_workspace_resource_to_folder via the 'personal folder' wording, though it does not explicitly name that 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 provides no guidance on when to use this tool versus sibling tools like add_workspace_resource_to_folder or remove_personal_resource_from_folder. It includes a scope note ('account:write') but lacks prerequisites, conditions, or exclusions, leaving the agent to infer when this route is appropriate.

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=true, and openWorldHint=true. The description adds the permission scope 'workspaces:write', which is useful. However, it does not explain behavior on edge cases (e.g., resource already in folder, nonexistent folder) or the effect of the position parameter. The description is consistent with annotations (no contradiction) but adds limited behavioral context beyond them.

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

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

The description is a single, concise sentence that front-loads the core action. It includes the scope parenthetically without clutter. Every word earns its place; there is 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 mutation tool with 5 parameters, no output schema, and no details on return values or error handling, the description is too brief. It does not mention idempotency implications, what happens if the resource is already in the folder, or any prerequisites (beyond the scope note). An agent would lack critical information to call this tool confidently in varied scenarios.

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 only 40% (folder_id and workspace_id have descriptions; resource_type and resource_id do not). The description does not compensate for this gap—it only restates that resource_type can be 'application or database' (already in the enum) and provides no meaning for resource_id or position. Since the description fails to clarify undocumented parameters, it adds minimal value beyond the schema.

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

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

The description clearly states the action ('Puts') and the resource type ('application or database') into a workspace folder. It differentiates from siblings like add_personal_resource_to_folder by explicitly mentioning 'workspace folder', and from removal tools by the action verb. The scope note adds context.

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 for workspace resources via the name and phrase 'workspace folder', but it does not explicitly state when to use this tool versus alternatives like add_personal_resource_to_folder or remove_workspace_resource_from_folder. No exclusions or conditions are given, leaving the agent to infer 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?

The description adds meaningful behavior beyond the annotations: the generated link cannot be revoked, it expires, and it works for private files. It also states the required scope, blob:read. With annotations already covering read-only and destructive behavior, this is a strong additive disclosure.

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 compact sentences plus a scope note. The key behavior is front-loaded, and every sentence adds relevant 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 simple three-parameter read-only tool with rich annotations and no output schema, the description covers purpose, lifecycle, privacy behavior, and authorization scope. It leaves workspace_id semantics and the exact return value unaddressed, but the core behavior is sufficiently complete.

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

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

Schema coverage is 67%, with id and expires_in described in the schema but workspace_id undocumented. The description does not explain any parameter, so it fails to add meaning or compensate for the partially covered 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 states a specific verb and resource: creating a temporary download link for a Blob Storage file. It also clarifies that private files are supported, but it does not explicitly distinguish this from sibling tools such as get_blob_object or list_blob_objects.

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 purpose: use this when a temporary download URL is needed, including for private files. However, the description does not say when to prefer this over a sibling like get_blob_object or how it relates to upload_blob.

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=true, so the safety profile is covered. The description adds value beyond that by disclosing the required auth scope (blob:read) and by enumerating the payload fields (files, used/total space, plan limits), which substitutes for the absent output schema. It does not mention rate limits, freshness/lag of the statistics, or whether workspace scoping changes the numbers.

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 states the resource first, then the returned fields, with the access scope tucked into a compact parenthetical. Nothing is padded, though the parenthetical scope clause could be separated for scannability.

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 read-only statistics tool with no output schema, the description adequately covers what comes back (files, used/total space, plan limits) and what permission is needed. The remaining gaps are the optional workspace_id's effect on scope and any indication of data freshness, neither of which is critical to invoking 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 description coverage is 0% for the single workspace_id parameter, and the description never mentions it. The description's phrase 'of the account' even leaves ambiguous whether omitting workspace_id returns account-wide or personal-scope usage. The parameter name is largely self-explanatory, but the description provides no compensating semantics for a documented coverage gap.

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 the specific resource (Blob Storage usage of the account) and enumerates the returned fields: files, used and total space, and plan limits. This distinguishes it from siblings that manipulate blobs (list_blob_objects, get_blob_object, upload_blob, set_blob_visibility), which all act on individual objects rather than reporting account-level usage. It stops short of naming a sibling explicitly, but the read-a-report framing 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: an agent can infer this is the call for checking storage consumption against plan limits. There is no explicit when-to-use statement, no mention of when to prefer it over list_blob_objects, and no stated prerequisites (e.g. whether it needs an active workspace context).

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

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

Beyond the annotations, the description discloses the key behavioral trait that nothing executes until a person approves the request in the dashboard, and it states the required workspaces:write scope. It does not contradict the annotations; destructiveHint=false is consistent because this tool creates an approval request rather than executing the deletion itself.

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 tight sentences plus a scope note, with the core approval-gating behavior front-loaded. Every sentence contributes useful context, and there is no redundant restatement of the tool name.

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

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

For a mutation-adjacent approval tool with annotations and a mostly described schema, the description covers the essential approval workflow and permission scope. It could be stronger by mentioning what the request returns or how to check approval status, especially since no output schema exists, but it is sufficient 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 75%, so the schema already documents most parameters, including the action enum and the conditional snapshot_id. The description adds no parameter-level meaning, such as which action values are supported or how resource_id relates to each action, so the baseline of 3 is appropriate.

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

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

The description states a clear approval-request purpose: it asks a permitted person to carry out an action the account cannot perform itself, and nothing runs until approval. It distinguishes this from direct mutation siblings by emphasizing human approval, but it does not explicitly enumerate the supported action types or name the direct 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 phrase 'the account can't do on its own' implies when to use this tool, namely when an action requires human approval. However, it does not explicitly say when not to use it or name sibling tools such as delete_app or restore_snapshot as alternatives when permission exists.

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

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

Annotations declare non-read-only, non-idempotent, open-world behavior, and the description adds substantial context beyond that: the call is asynchronous and returns immediately in 'building' status, specific failure codes and remedies, and the paid-plan prerequisite. This is exactly the behavioral disclosure annotations alone cannot convey.

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

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

Front-loaded with the core action, then the async/polling contract, then the error matrix. Dense but every clause is actionable; it runs long, though the remediation mapping justifies most of the length.

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 still explains the return contract (immediate return, 'building' status) and how to observe completion or failure. Combined with annotations, an agent has enough to invoke and follow up 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 70%, so most parameters are already documented; the description adds real meaning only for `path` (which folder contents are compressed/ignored). The other parameters (memory, main, build, start, version, subdomain, workspace_id) are left to the schema, which is acceptable at this coverage level but not compensating further.

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 ('Creates an application from a folder') plus the mechanism (compress, ignoring node_modules/.git/.vertraignore, then upload). This clearly distinguishes it from siblings like deploy_app or upload_files, which create/deploy different artifacts.

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 covers what to do after the call (poll wait_for_app/get_app_status until 'up' or 'down'), an error-code-to-action mapping for last_build_error, the 409 APP_BUILDING conflict during builds, and the PLAN_REQUIRED condition. An agent has no inference left to make.

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

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

Adds substantial behavior beyond the annotations: asynchronous 'building' status, required polling tools, error codes IMAGE_NOT_READY and PLAN_REQUIRED, and the meaning of web true vs false including port injection as PORT. With annotations already covering safety, this is rich and useful context.

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

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

Front-loads the core action and image precondition, then packs error codes, async behavior and web semantics into subsequent sentences. The nested parentheticals about suggested_port and PORT are dense, but almost every clause carries operational 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 complex async creation tool with no output schema, the description covers the critical call flow: precondition, returned status, polling path and publishing semantics. Minor gaps remain around environment variables, memory sizing and what identifiers the response returns, but these are largely covered by the schema or implied.

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 high (89%), so the baseline is 3, but the description adds real meaning for web, port and subdomain: web true publishes the app, port defaults to the image's suggested_port (first EXPOSE or 80), and subdomain/port only apply with web true. It does not clarify memory, envs, description or workspace_id 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 ('Creates an application') and qualifies the source ('runs from a custom image'), which distinguishes it from the sibling create_app that presumably uses a runtime. It does not explicitly name create_app as the alternative, so sibling differentiation 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?

Gives clear preconditions (image status must be 'success', otherwise IMAGE_NOT_READY) and the post-call pattern (poll wait_for_app or get_app until 'up'/'down'). It also explains that PLAN_REQUIRED occurs for accounts without a plan. It lacks an explicit statement of when to prefer this over create_app.

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

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

Annotations only give the generic readOnly/destructive/idempotent/openWorld flags; the description adds real behavioral context: an auth scope (databases:write), the PLAN_REQUIRED failure mode with its remediation, the INVALID_DATABASE_VERSION failure, and the important irreversibility that an existing database's version can never be changed. That is well beyond what structured fields convey.

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

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

Purpose is front-loaded in the first sentence, then prerequisites, then parameter guidance, then the immutability caveat. Every sentence carries information, though the version discussion is dense enough that it could be split for readability.

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 6-parameter creation tool with no output schema, the definition never states what is returned (e.g. the new database object or its id) and leaves `name`, `workspace_id`, and `description` unexplained. The failure modes and immutability are covered well, but the missing parameter and return context leaves it incomplete.

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 only 33%, and the description only compensates for `version` (engine version line, omit for recommended, never a patch, error on invalid). It says nothing about `name`, `workspace_id`, or `description`, and adds little on `engine` beyond what the enum already shows, so half the parameters remain undocumented in either place.

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 opening sentence "Creates a managed database" gives a specific verb and resource that cleanly separates it from siblings like create_app, create_image, create_role, or update_database. Scope 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?

It states a prerequisite gating condition (accounts without a plan get PLAN_REQUIRED, a paid plan is needed first) and routes the agent to `list_database_versions` for valid version lines before calling. There is no explicit statement of when to prefer an alternative or when not to call, so it stops short of a 5.

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

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

Annotations already disclose that the tool is destructive, non-read-only, non-idempotent, and open-world. The description adds useful behavioral context beyond that by naming the required scope (apps:write) and the precondition that the repository must already be connected, though it does not elaborate on what existing webhook configuration may be replaced.

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 one compact sentence plus a scope marker, with the operation front-loaded and no wasted wording. It conveys the core action and prerequisite efficiently.

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 seven-parameter mutation with no output schema, the description gives the essential operation, prerequisite, and required scope, while the schema documents parameters and annotations cover the safety profile. It is largely complete, though it could do slightly more to clarify the effect on an existing webhook or how this relates to sibling webhook tools.

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 86%, so the parameter documentation is already strong and the baseline is 3. The description adds only general context about the application and connected GitHub repository, without adding meaning beyond the schema for any specific 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?

The description states a specific verb and resource: creates or renews the application's automatic-deploy webhook. The operation is clearly distinguishable from sibling tools such as get_deploy_webhook and delete_deploy_webhook by the create/renew action.

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

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

It implies the prerequisite that the GitHub repository must already be connected, which is useful context. However, it does not explicitly say when to use this instead of get_deploy_webhook, delete_deploy_webhook, or deploy_app, nor does it state when not to use 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?

Goes well beyond the annotations by disclosing that the call is asynchronous and returns status 'building', that builds rebuild on push only for linked GitHub App installations, and that public repos outside installations build once. It also enumerates failure codes (INSTALLATION_NOT_FOUND, PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES, MAX_IMAGES_REACHED) and the scope required (images:write).

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-loads the core action and source constraints before the async/error details, and every sentence carries operational information. It runs long with deeply nested parentheticals, but no sentence is truly expendable.

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

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

For a mutation tool with no output schema, it covers the return behavior (status 'building'), the polling loop, the log tool, source prerequisites, and error outcomes. An agent has everything needed to invoke and follow up 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%, but the description still adds meaning the schema lacks: which files are ignored when zipping a folder (node_modules, .git, .vertraignore), that path and github_repository are exclusive, and that github_branch defaults to the repo default. The 128-character description constraint merely repeats 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?

Opens with a specific verb and resource ('Creates a custom Docker image') and immediately bounds the accepted sources to exactly one of two paths. This clearly separates it from siblings like create_app_from_image, update_image, and rebuild_image.

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?

States the mutually exclusive source options, the 100 MB limit, and the required Dockerfile at root, so an agent knows the preconditions for calling it. It also routes follow-up work to get_image and get_image_build_log, though it never contrasts itself with nearby siblings such as create_app_from_image.

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 non-read-only, non-destructive, open-world, non-idempotent; the description adds real value by disclosing the specific failure mode (BILLING_DETAILS_INCOMPLETE), the return payload (price with coupon discount and order_id), and the downstream effect on app/database creation. It doesn't state whether repeated calls spawn duplicate orders, which matters given non-idempotentHint.

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 dense sentences, front-loaded with purpose, then prerequisite/failure, then downstream consequence. No filler, though the billing sentence is long enough to be slightly heavy for scanning.

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 compensates by naming the return values, and it covers prerequisites and failure behavior for a mutation tool. The remaining gap is what happens after creation (how the order gets paid, e.g. via get_pix or redeem_code), which the agent must infer.

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 plan, coupon, and the months pricing tiers. The description only echoes that a coupon discount affects the returned price and adds no syntax or format detail beyond that, 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?

States a specific verb and resource ('Creates a plan subscription order') plus what it returns (final price and order_id), which cleanly separates it from list_orders and get_order_status. An agent can identify it 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 a clear prerequisite (complete billing details) and routes the agent to set_billing_details when the BILLING_DETAILS_INCOMPLETE failure occurs, plus the consequence of not paying. It lacks explicit 'when not to use' guidance versus list_orders/get_order_status, but the actionable conditions are clear.

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

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

Annotations already convey read-only/idempotency/destructive hints, and the description aligns with readOnlyHint=false. It adds the 'scope: account:write' permission context, which is useful, but discloses nothing about side effects such as duplicate name handling or visibility.

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 sentence plus a scope note, no filler. The primary action is front-loaded and the scope hint 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 creation tool with three undocumented parameters and no output schema, the description is too thin. It omits what each parameter controls and what the call returns, and the 'organize' clause only hints at the folder's purpose, not the API contract.

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 0%, so the description must compensate, but it provides no meaning for 'name', 'color', or 'position'. The folder's purpose does not explain parameter choices, leaving only the schema's enum/constraints as guidance.

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 'creates' and resource 'personal folder', and defines its purpose as organizing applications and databases. The 'personal' qualifier distinguishes it from workspace-folder siblings, and the scope note adds precision.

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 phrase 'to organize applications and databases' implies a use case but gives no explicit when-to-use or when-not-to-use guidance. It does not contrast with alternatives like create_workspace_folder or mention any preconditions.

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=true, so the safety profile is largely covered. The description adds the required OAuth-style scope (workspaces:write), which is genuinely useful, but says nothing about name uniqueness, duplicate-role failure behavior, or what gets 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, front-loaded sentences with no filler. It is efficient, though the brevity is partly under-specification rather than disciplined concision.

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 four-parameter mutation with 75% of parameters undocumented in the schema and no output schema, the description should explain the permissions format and required vs optional fields. It leaves an agent guessing about the most error-prone input, the permissions array.

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 only 25% — id is documented, while name, position, and permissions are bare. The description does not compensate by explaining permission string formats, the meaning of position/ordering, or constraints such as minimum length or uniqueness.

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 ("Creates a role") plus a context ("in the workspace"), so the action is unambiguous. However, it barely goes beyond restating the tool name and offers no differentiation from siblings like update_role, delete_role, or list_roles.

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 call this versus update_role or list_roles, and no prerequisites such as workspace membership or admin rights. The "(scope: workspaces:write)" note hints at authorization but is not usage 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 non-read-only, non-idempotent, non-destructive and open-world. The description adds two genuinely non-obvious traits: the operation consumes the plan's snapshot quota, and it requires the snapshots:write permission scope. Not disclosed: whether snapshotting is async, how long it takes, or what happens at quota limit.

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 cost, then permission. Nothing is padded, though the parenthetical scope token is terse to the point of ambiguity.

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 should say what a successful call yields (a snapshot object with an ID the agent could feed to restore_snapshot or download_snapshot). It covers side effects and auth but leaves the return value undefined.

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 an enum on scope, so both parameters are already fully documented, and the description adds no param-level detail. The '(scope: snapshots:write)' parenthetical is a permission scope, not the 'scope' parameter, which could momentarily confuse a reader. 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?

Specific verb+resource: 'Takes a snapshot of the resource.' An agent can tell this creates a snapshot, distinct from list_snapshots/restore_snapshot/download_snapshot. However, 'the resource' is left vague in the prose; only the schema reveals it is an application or database, and 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 by the nature of the operation but never stated: nothing says when to snapshot versus restore, and no prerequisites or exclusions are given. The only guidance is the quota warning, which is a cost note rather than a when-to-use rule.

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

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

Annotations already convey that this is a non-read-only, non-idempotent, non-destructive operation. The description adds the required OAuth scope 'workspaces:write', which is useful auth context. It does not disclose side effects, uniqueness constraints, or behavior on conflicts, but the annotations cover the main safety profile.

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 one short sentence plus a parenthetical scope annotation. It front-loads the core action and contains no filler. It is concise, though its brevity leaves out useful behavioral and parameter 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 create operation with no output schema, the description should explain what creation entails, what fields are expected, and what the agent should expect afterward. It provides none of that beyond 'Creates a workspace.' The openWorldHint and idempotentHint annotations hint at additional complexity, but the description does not clarify 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 description coverage is 0%, and the description adds no meaning for the 'name' or 'description' parameters. An agent gets no guidance on what 'name' should look like, whether 'description' is optional, or what valid values are. The description fails to compensate for the absent schema descriptions.

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

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

The description states a specific verb and resource: 'Creates a workspace.' This clearly identifies the operation and distinguishes it from sibling tools like update_workspace, delete_workspace, and list_workspaces. However, it does not explicitly contrast with related tools such as create_workspace_folder, so it is not fully 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 gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. An agent must infer from the name that this is the right call for creating a workspace, which is not enough for a toolset with many similar workspace-related operations.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-idempotent. The description adds an explicit authorization requirement, "(scope: workspaces:write)", which is useful behavioral context beyond the annotations. There is no contradiction with any annotation.

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

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

The description is one efficient sentence with a short scope note appended. It is front-loaded and free of filler, meeting conciseness expectations, though the scope note is slightly cryptic.

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 create operation with annotations, the description adequately conveys purpose and permission scope. However, it lacks parameter explanations, does not mention return behavior (no output schema exists), and does not disambiguate from related folder tools explicitly, leaving moderate 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?

Schema description coverage is only 25%, with only workspace_id described ('Workspace ID'). The description adds no meaning for name, color, or position, and does not compensate for the low coverage. Param names and the color enum are somewhat self-explanatory, but the description itself provides no parameter semantics.

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

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

The description states a specific verb and resource ("Creates a workspace folder") and further clarifies the purpose ("to organize applications and databases"). The resource type and verb distinguish it from sibling tools like create_personal_folder and delete_workspace_folder, though it does not explicitly name any sibling 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 purpose clause implies when to use the tool: when a folder is needed to organize applications and databases. However, it gives no explicit when-not-to-use guidance and does not mention alternatives such as create_personal_folder or update_workspace_folder, so usage context is only implied.

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; the description adds the concrete consequence that the invite 'stops being valid,' which tells the agent the state change is permanent and the token cannot be reused. It does not explain what a second call returns or what error occurs on an expired/invalid token, 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?

A single front-loaded sentence carrying the action, its guarantee, and its effect, plus a compact scope tag. Nothing is redundant.

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, no-output-schema tool whose annotations cover the safety profile, this is nearly complete: the action, the scope, and the resulting state are all stated. Error/failure behavior for invalid or already-used tokens is the 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?

Only one parameter exists and schema description coverage is 100%, with the schema itself explaining the token is 'the final part of the link.' The description adds nothing about the token, 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?

Names a specific verb and resource ('Declines an invite') and states the scope ('without joining the workspace'), which distinguishes it from accept_workspace_invite and preview_workspace_invite. 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?

Usage is only implied: an agent can infer this is for invitees who do not want to join, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as revoke_workspace_invite for admins. No prerequisites (e.g., must be the invitee, token must be unexpired) 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description earns credit by adding that files and configuration are destroyed along with the app and by surfacing the required auth scope (apps:delete), which annotations do not convey. It stops short of noting cascade effects or whether dependent resources (deploys, domains, envs) are affected.

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 zero filler; the permanence and destruction scope are front-loaded, and the auth scope is a compact parenthetical. Nothing is 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?

For a simple two-parameter destructive tool with full annotation coverage and no output schema, the description gives an agent enough to act: what is deleted, that it is permanent, and the required scope. Missing only peripheral detail such as cascade behavior and whether a confirmation or prior stop is needed.

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 'id' and 'workspace_id' documented in the schema itself, so the baseline is 3. The description adds no meaning about the parameters, such as whether workspace_id is required for scoping the lookup in multi-workspace accounts.

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 deletes the application') plus the blast radius ('along with its files and configuration'), which is more informative than the bare name. It does not explicitly distinguish itself from delete_database, delete_workspace, or delete_file, but the resource noun makes the target 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?

No guidance on when to use this versus alternatives such as stop_app, unpublish_app, or remove_app_from_workspace, and no prerequisites or warnings about irreversible consequences beyond the word 'Permanently'. The agent must infer the usage context 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 destructiveHint=true and idempotentHint=false, so the description doesn't need to restate danger. It does add genuinely new context: the public URL stops working (side effect) and the required blob:write scope (auth need). Still no statement on irreversibility or confirmation 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?

Three short, front-loaded clauses with no filler; the action comes first and the consequence second. The parenthetical scope tag is slightly awkward but compact.

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 delete with full annotation coverage, the description is close but leaves the undocumented workspace_id and the lack of any recovery/irreversibility note 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 only 50% – 'id' is documented but 'workspace_id' has no description anywhere. The description compensates for neither, so the agent must infer whether workspace_id is needed to scope the deletion.

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 ('Deletes') and resource ('one file from Blob Storage'), which distinguishes it from the many folder/app/database delete siblings. It doesn't contrast with delete_file, but the 'Blob Storage' qualifier is enough to route correctly.

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 indication of when to use this versus delete_file or the folder-removal siblings, and no prerequisites or warnings about irreversibility. The parenthetical scope tag is a permission note, not usage 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?

The annotations already mark this as destructive and non-idempotent. The description adds useful behavioral context by stating that the deletion is permanent and that data inside the database is destroyed, going beyond the structured hints.

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

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

The description is two short sentences with no waste. It front-loads the permanent destructive action and then appends the scope compactly.

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 destructive mutation with annotations covering safety and no output schema, the description is largely complete. The main gap is the unexplained optional workspace_id parameter, but the core deletion behavior and data-loss consequence are clear.

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 only 50%: the id parameter is documented as 'Database ID', but workspace_id has no description in the schema or tool description. The description adds no semantics for either parameter, so the undocumented workspace_id remains 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 clear verb and resource: permanently deletes the database and its data. It is specific enough to distinguish from get_database or update_database, but it does not explicitly differentiate from reset_database or stop_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 word 'Permanently' implies this is for irreversible removal, but the description gives no explicit when-to-use guidance, prerequisites, or alternatives such as reset_database or stop_database. The agent must infer the correct context.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false, so the safety profile is covered structurally. The description does add real value with the concrete effect ('whoever was using the URL stops being able to deploy') and the required scope, but says nothing about what happens when the id does not exist or whether the operation is reversible.

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 clauses, front-loaded with the action and its consequence, plus the scope in parentheses. Nothing is redundant, though the parenthetical scope could arguably be conveyed structurally.

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-param tool with no output schema, the description covers the effect and the auth scope, which is a reasonable core. It still leaves the undocumented workspace_id and the not-found behavior unaddressed, which matters for a delete operation.

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

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

Schema coverage is 50%: 'id' is documented as the Application ID, but 'workspace_id' has no description anywhere. The description does not compensate – it never mentions either parameter, so the agent gets no guidance on whether workspace scoping is required or what happens if it is omitted.

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 ('Removes the automatic-deploy webhook') and adds the consequence, which pins down exactly which object is affected. It is distinguishable from create_deploy_webhook and get_deploy_webhook by the resource name, though those siblings are never 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 only implied: an agent can infer this is the revocation path for auto-deploy, but there is no explicit when-to-use/when-not guidance, no mention of prerequisites for obtaining the id, and no alternative named if the intent is only to pause deploys temporarily.

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 openWorldHint=true, so the agent knows this is an unrecoverable mutation. The description contributes the required OAuth scope ('apps:envs'), which is genuinely useful auth context not present in annotations. It is diminished, however, by failing to state irreversibility plainly and by misidentifying which parameter holds the variable 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?

Two short sentences with the core action front-loaded and the dependency second; little waste. The parenthetical scope note is compact and earns its place, though the misleading `id` reference costs it a point.

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, so the description need not explain returns, and annotations carry the safety profile. But with a partially documented schema (67%) and an ambiguous `workspace_id`, plus the incorrect `id`/`env_id` mapping, an agent could still misconstruct the call.

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 description says to use 'the variable `id`', but the schema defines `id` as the Application ID and `env_id` as the Variable ID — so the guidance actively misdirects the agent on the required parameters. Coverage is only 67% (workspace_id is undocumented in both places), and the description adds no correct semantics for env_id or workspace_id.

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 ('Deletes an environment variable'), which is clearly distinct from the sibling tools set_env and list_envs. It does not explicitly name those siblings as alternatives, so it falls just 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 sentence 'Use the variable `id` returned by `list_envs`' gives a clear upstream dependency and points at a sibling for obtaining the value. However, there is no guidance on when not to delete, no mention that existing values are lost irreversibly, and no mention of the set_env alternative for modification.

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 largely covered. The description adds the OAuth scope ('apps:files'), which is genuinely useful context, but omits whether folder deletion is recursive, whether the operation is reversible, and what happens to the path/id relationship — meaningful for 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?

Two short sentences with no filler, and the action is front-loaded. It is efficient but arguably too terse given the destructive nature of the 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 no output schema and 67% of parameters undocumented, the description should clarify permanence, recursion behavior for folders, and path semantics. It does none of these, leaving the agent under-informed before an irreversible call.

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 only 33%: only 'id' carries a schema description, while 'path' (required) and 'workspace_id' are undocumented. The description compensates for none of this — it never explains how 'path' interacts with 'id', whether path is relative to the app root, or what workspace_id scopes.

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 ('Deletes a file or folder from the application'), which is clear enough to act on. However, it doesn't distinguish itself from the several folder-deletion siblings (delete_workspace_folder, delete_personal_folder, delete_app), and the 'file or folder' phrasing actually widens scope beyond the tool name.

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 tool versus delete_workspace_folder, delete_personal_folder, or delete_app, nor any prerequisites (ownership, permissions, whether the app must be stopped). The only hint is the parenthetical scope string.

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 annotation by disclosing exactly what is destroyed (versions, build context, dependent apps), the exact-match confirmation requirement, the refusal condition during builds, and the extra apps:delete scope needed when apps exist. This is rich behavioral context an agent needs before a destructive call.

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-loads the destructive scope in the first clause, then layers confirmation, refusal, and scope requirements as terse, information-dense sentences. No wasted words.

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

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

No output schema exists, but the description covers the destructive outcome, confirmation contract, error conditions, and scope requirements, which is everything an agent needs to invoke this mutation 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 coverage is 100%, so baseline is 3; the description adds value by explaining the confirm_name semantic (exact image name required, else IMAGE_NAME_MISMATCH) and the scope interaction tied to apps. The workspace_id parameter is left to the schema, keeping it at 4 rather than 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?

States a specific verb (DELETES permanently) and resource (image), and explicitly enumerates the cascade: versions, build context, and every application created from it. This distinguishes it clearly from siblings like delete_app or delete_file.

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 concrete preconditions and failure modes: confirm_name must match exactly or IMAGE_NAME_MISMATCH, and the call is refused with IMAGE_BUILD_IN_PROGRESS during a build. It does not name alternative tools (e.g., get_image before deleting), so it stops short of explicit when-vs-alternative 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?

The annotations already mark this as destructive, but the description adds important behavioral context beyond that flag: deleting the folder does not delete the resources inside it. The explicit '(scope: account:write)' also communicates an authorization scope not present in the annotations.

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

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

The description is extremely concise and front-loads the core action first, followed by the critical non-destructive-of-contents nuance. The scope note is compact and not redundant with the schema 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?

For a one-parameter delete operation, the description covers the main behavior, the side-effect nuance regarding contained resources, and the required scope. It does not explain return values or error behavior, but the absence of an output schema and the simplicity of the tool make the description otherwise 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%, and the only parameter, folder_id, is already described as 'Folder ID'. The description adds nothing about parameter formats, formats, or validation beyond what the schema already provides, 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 opens with a specific verb and resource, 'Deletes a personal folder', and the added detail that resources inside it are not deleted clarifies exactly what the operation does. The term 'personal' distinguishes this from sibling tools like delete_workspace_folder, so an agent can tell it apart from related folder deletion tools.

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

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

The intended use case is implied by the resource type: this deletes a personal folder, not a workspace folder. However, it never explicitly says when to use this over siblings such as delete_workspace_folder or the remove-resource-from-folder tools. There is clear context but no explicit 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the bar is lower; the description still adds real value by disclosing the downstream effect on members who currently hold the role and by naming the required scope (workspaces:write). It does not address whether assignment must be removed first or what happens on failure, but the key blast radius is stated.

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 carrying the action, the consequence, and the auth scope, with no filler. Every clause 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 destructive, non-idempotent mutation with no output schema, the description conveys outcome and scope, which covers the main decision points. It leaves the semantics of role_id and any error/precondition behavior (e.g., role still assigned to members) unexplained, so it is adequate rather than 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 only 50%: workspace 'id' is documented in the schema while 'role_id' is an undescribed bare string in both schema and description. The description adds no meaning for either parameter, so it fails to compensate for the coverage gap on the undeclared role identifier.

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 ('Deletes a role') plus the concrete consequence for holders of the role. It is easily distinguished from create_role/update_role/list_roles by the verb, but the description never names those alternatives explicitly, so it stops 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?

The consequence clause ('whoever had it loses those permissions') implicitly warns that this is a high-impact cleanup action, and the scope marker hints at required permissions. There is no explicit when-to-use vs. when-not framing, no mention of choosing update_role instead when only permissions should change, and no stated prerequisites.

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 flag destructiveHint=true and idempotentHint=false, and the description goes well beyond that by enumerating what is destroyed (members, roles, invites, links) and what survives (apps and databases return to the owning account) plus 'This cannot be undone.' That is exactly the consequence detail an agent needs before a destructive call and cannot get from the hints.

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

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

Three compact sentences with zero filler: action and permission first, consequences second, irreversibility third, scope tag last. Every clause carries decision-relevant 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 destructive mutation with no output schema, the description covers the authorization gate, the full set of destroyed entities, the fate of dependent resources, and irreversibility. Nothing an agent needs in order to call this safely 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 coverage is 100% and the single 'id' parameter is documented in-schema as 'Workspace ID'. The description adds no syntax, format, or lookup guidance for that id, so the baseline 3 applies — the schema is doing the 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 ('Deletes the workspace') and immediately scopes it ('owner only'), which is enough to separate it from delete_workspace_folder or delete_personal_folder without opening either schema. It also names the object type being removed, so the agent knows the blast radius is the workspace itself rather than a contained folder.

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 parenthetical '(owner only)' gives a hard precondition that determines whether the agent should call it at all, which is real usage guidance. It stops short of explicitly routing to alternatives (e.g. remove_app_from_workspace or delete_workspace_folder for narrower actions), so there is no stated when-not-to-use.

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

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

Annotations already mark the operation as destructive and non-idempotent. The description adds valuable behavioral context beyond the annotations: resources inside the folder are not deleted, and the operation requires the workspaces:write scope. This helps an agent understand the partial-destruction semantics 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?

The description is a single, well-structured sentence that front-loads the core action and immediately adds the critical non-destructive nuance. The scope parenthetical is compact and useful. No unnecessary words or repetition.

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

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

For a simple two-parameter delete operation, the description combined with annotations and full schema coverage is nearly complete. It explains the key behavioral outcome (resources survive) and the required scope. It does not mention return values or error cases, but this is minor for such a low-complexity 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%, with both workspace_id and folder_id described in the schema. The tool description adds no additional parameter-level semantics, so it relies on the schema, which is sufficient. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Deletes a workspace folder'. It also clarifies the scope of the deletion by noting resources inside are not deleted, which distinguishes it from broader destructive tools like delete_workspace and from personal folder operations. This is unambiguous and immediately actionable.

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 when to use the tool—when you want to delete a workspace folder—but it does not explicitly mention alternatives or state when not to use it. The sibling list and the 'workspace folder' wording provide context, but no direct routing guidance is 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 only declare destructive/openWorld/non-idempotent; the description adds real behavior: the 409 APP_BUILDING failure mode, that on custom-image apps the upload becomes a commit that rebuilds the image, that the application restarts on build success, and that the response carries `message` and `image_build`. It stops short of saying what prior deploy state is replaced or the auth/scope implication of a failed scope check, hence not 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?

Front-loaded with the core action, then error handling, then custom-image behavior, then scope — a sensible priority order. The final sentence is dense (two scopes, one attached mid-sentence) and slightly awkward, keeping it from a 5.

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 upload with no output schema, the description covers the important failure mode, side effects (rebuild + restart), returned fields, and required scopes. Gaps remain on what upload overwrites and on the behavior of the `restart=false` path, which matters for a destructive 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 coverage is 80%, so the schema already documents id, path, message, restart, and bounds. The description adds no meaning for the `restart` flag or `workspace_id`, and mentions `message` only as a result field, not as the release-history argument. Baseline 3 applies since the schema carries the parameter load.

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 (upload a folder to an existing application, i.e. a new deploy) and scopes it to existing apps, which separates it from create_app and from sibling upload tools like upload_files and download_app. The parenthetical '(new deploy)' disambiguates that this produces a deploy rather than a plain file write.

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 conditional guidance: on 409 APP_BUILDING 'wait with `wait_for_app` first', and references create_app for compression parity. It does not, however, say when to choose deploy_app over upload_files or publish_app, or what prerequisites the app must satisfy beyond being past its first build.

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 and idempotentHint=true, so the safety profile is covered. The description adds two useful facts beyond that: the payload is a zip bundle of all app files, and the operation writes a file to a caller-supplied path (a local side effect), plus the required apps:read scope. It does not say whether an existing file at dest is overwritten.

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 result, with the scope note appended in parentheses. 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 three-parameter, fully documented, annotation-covered tool with no output schema, the description covers purpose, output artifact, destination side effect, and permission scope. Only overwrite semantics for dest is a meaningful omission.

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 schema already documents id, dest (explicitly "Path of the .zip file to write"), and workspace_id. The description's mention of "given path" and "zip" adds nothing beyond the schema, 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 ("Downloads the application's files as a zip") plus the destination behavior ("writes it to the given path"). This clearly separates it from siblings like download_snapshot, blob_download_url, or read_file, though it never names an alternative 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 by the resource naming, but there is no explicit guidance about when to prefer this over read_file, get_file_tree, or upload_files. The only directive-style content is the scope note (apps:read), which speaks to permissions rather than tool selection.

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 usefully adds that the operation has a local side effect, writing a file at the supplied path, but says nothing about overwrite behavior, missing directories, snapshot readiness, or file size limits.

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 core action plus its output effect are front-loaded before the scope note.

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, so the description must convey the result; it does say a file is written, but leaves open whether anything is returned, whether an existing file is clobbered, and what happens if snapshot_id is invalid. For a four-required-parameter download tool this is adequate but has clear 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?

Schema coverage is 75%; dest, scope and resource_id are already documented in the schema, and snapshot_id is undocumented in both places. The description's phrase 'given path on the computer' usefully confirms dest is a local filesystem path, but it does not explain the scope-to-resource_id relationship (application vs database) or what snapshot_id refers to.

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 (downloads) and resource (a snapshot) plus the destination behavior ('writes it to the given path on the computer'), which is more than a restatement of the name. It does not explicitly separate itself from restore_snapshot or download_app, but the file-output framing is distinctive enough for an agent to identify it.

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 choose this over restore_snapshot (which acts in-place) or download_app, nor on prerequisites such as the snapshot having finished creating. The only contextual cue is the '(scope: snapshots:read)' suffix, which indicates a permission rather than a selection rule.

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

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

The description adds the scope 'account:write' which is beyond the annotations, signaling write permissions. Annotations already declare idempotentHint true and destructiveHint false, so the description does not need to restate those. It provides a small but useful additional behavioral detail.

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

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

The description is a single, front-loaded sentence that states the action and scope. No extraneous words, and it is appropriately sized for the tool's simplicity.

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

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

The description is too sparse for a tool with three parameters and no output schema. It omits parameter meanings, any prerequisites, and the expected response. While the action is simple, the lack of parameter detail makes the definition incomplete.

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 description does not explain any of the parameters (resource_type, resource_id, position). Schema coverage is 0%, so the description must compensate, but it only hints at resource_type via the phrase 'application or database'. resource_id and position remain unexplained, leaving the agent to guess.

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

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

The description clearly states the verb 'adds' and the resource 'application or database' to 'personal favorites', distinguishing it from workspace favorites. The name and description together make the purpose unambiguous, and it is distinct from sibling tools like favorite_workspace_resource.

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 personal vs workspace favorites but does not explicitly contrast with alternatives like favorite_workspace_resource or explain when to choose this over them. No exclusions or conditional guidance are provided; the agent must infer 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 convey mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds the auth scope 'workspace:write', which is useful, but does not clarify duplicate handling, ordering behavior, or whether the resource must already exist in the workspace.

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 entire description is one front-loaded sentence with the scope note in parentheses. It contains no filler or repetition of schema properties and 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 straightforward favorite operation, the description is minimally viable: it names the action, target, and permission scope. However, it leaves behavioral details like position semantics and relationship to workspace membership unexplained, making the overall context adequate but incomplete.

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 only 25%, with only workspace_id documented. The description loosely maps to resource_type by naming 'application or database' but adds no meaning for resource_id or the optional position parameter. It does not compensate for the low schema coverage.

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

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

The description states a specific verb ('Adds'), a specific resource type ('application or database'), and a specific destination ('workspace favorites'). This clearly differentiates it from sibling tools such as favorite_personal_resource, add_app_to_workspace, and unfavorite_workspace_resource.

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 versus alternatives such as favorite_personal_resource or add_workspace_resource_to_folder. The scope note 'workspace:write' hints at permission requirements, but the description provides no when-to-use or when-not-to-use context.

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

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

Annotations already declare this as a safe, idempotent read. The description adds useful behavioral context: it lists returned fields, explains last_build_error semantics and remediation steps, and states the required apps:read 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?

The description is front-loaded with the main return fields, then error-code guidance. It is dense but every sentence serves a purpose, though the error-code mapping is lengthy enough to be slightly heavy.

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

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

Given no output schema, the description adequately covers the main returned fields and error behavior. It does not fully explain workspace scoping or contrast with get_app_status, but annotations and schema cover safety and parameter details.

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 id and workspace_id are already documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides, which is acceptable at baseline 3.

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 resource and enumerates the app details returned (name, status, memory, runtime, main file, publication). It implies a single-app lookup, distinguishing it from list_apps, but does not explicitly distinguish it from the sibling get_app_status.

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

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

Provides error-handling guidance routing the agent to get_logs for BUILD_FAILED/INSTALL_FAILED and explaining other last_build_error remedies. However, it does not say when to use get_app versus get_app_status or other detail/status 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, idempotentHint and destructiveHint=false, so safety is covered. The description adds the required permission scope ('apps:read') and the metric set, but says nothing about freshness cadence, pagination, or result ordering for the all-apps case.

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 compact clauses front-load the resource and metric set, then the no-id fallback. Nothing is padded and the scope tag is a single trailing parenthetical.

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 burden and does name the three metrics returned. Adequate for a read tool whose annotations already encode the safety profile; only the shape/order of the all-apps list is 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?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema lacks: omitting the optional `id` changes the result from one app to all apps. That optionality semantics is not derivable from the schema's bare 'Application ID' text. `workspace_id` is left entirely to 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+resource combination ('Live status ... of an application') and enumerates the returned metrics (CPU, RAM, uptime), which separates it from get_app or get_metrics without naming them. It stops short of explicitly distinguishing itself from those siblings, which keeps it at 4.

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 clause 'without `id`, of all of them' tells the agent exactly when to pass an id and when to omit it, so the two usage modes are clear. No sibling alternatives or exclusions are named, which is the only gap.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuine context: the exact fields returned, that CPF/CNPJ is masked, that `null` is returned until details are saved, and the scope (billing:read). This is meaningful behavioral disclosure beyond what annotations provide.

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

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

A single front-loaded sentence with no wasted words; the return content leads and the `complete`/`null` semantics and scope follow. Efficient, though the implied verb makes it slightly less crisp than it could be.

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 parameters and no output schema, the description compensates well by enumerating return fields and explaining the `complete` flag and null state. Nothing an agent needs to invoke it is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description correctly introduces no parameter syntax, and there is nothing for it to disambiguate.

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 the specific resource (the account's billing details) and enumerates its contents (name, address, phone, masked CPF/CNPJ) plus the `complete` flag, so an agent understands what it retrieves. The retrieval verb is implicit, but the noun-phrase framing still clearly distinguishes it from the sibling `set_billing_details`.

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 when-to-use statement, no prerequisites, and no named alternative (e.g. `set_billing_details`). The only hint is that `complete` indicates whether the details are 'enough to create an order', which loosely implies relevance before order creation, but the agent must infer the trigger condition.

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 a safe read-only operation. The description adds valuable non-obvious context: the blob path comes from untrusted content and must be treated as data, plus the required blob:read 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?

The purpose is front-loaded in the first sentence, followed immediately by the security warning and scope. Every sentence 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 simple read-by-id tool with strong annotations, the description covers the returned details and adds important security context. The only meaningful gap is the undocumented workspace_id parameter.

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 only 50%: id is documented, workspace_id is not. The description does not clarify what the id identifies, how workspace_id scopes the lookup, or how the two parameters interact, so it fails to compensate for the schema gap.

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: returns details of one Blob Storage file. It also names the returned fields, so it is clearly distinguishable from list_blob_objects and upload/delete siblings.

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

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

The purpose implies when to use it, but there is no explicit comparison to alternatives such as list_blob_objects or blob_download_url. No when-not-to-use guidance or prerequisites are stated beyond the scope label.

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, open-world behavior. The description adds useful context beyond that: the API never returns the password, the connection string contains a `<password>` placeholder, and the server does not execute queries. It does not discuss permissions or rate limits, but it covers the key credential-handling caveats.

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 tight sentences that front-load the returned connection data and follow with the critical password/query-execution caveats. Every sentence earns its place, with no repetition or 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?

With no output schema, the description does a good job listing the returned fields and clarifying the password placeholder and CA certificate format. It is missing detail about the `workspace_id` parameter and does not describe response structure beyond the field list, but overall it is complete enough for an agent to call 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?

There are two parameters, but schema description coverage is only 50%: `id` is documented as the database ID while `workspace_id` is undocumented. The description does not explain either parameter or compensate for the missing `workspace_id` semantics, so it adds little 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 states a specific resource and return payload: connection details including address, port, engine, user name, CA certificate, and connection string. It clearly distinguishes this credential-retrieval operation from query execution by saying the server does not run queries, so an agent can identify it 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?

Use is implied: retrieve this when you need to connect to the database yourself, and the caveat that the server does not run queries helps frame the use case. However, it does not explicitly compare this tool with siblings such as get_database or get_database_status, nor does it state when not to use 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 declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine context beyond that: the required permission scope (databases:read) and the constraint that an existing database's version cannot be changed, which steers the agent away from attempting version edits via update_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 returned fields, then the version constraint, then the scope tag. No wasted prose, though the field enumeration and the scope suffix read as terse fragments rather than polished 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?

There is no output schema, so the description must carry the return shape and it does by listing exactly which attributes come back. The remaining gap is the undocumented workspace_id parameter and the lack of any routing against the many adjacent database tools.

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 only 50% and the description does not compensate: id is described in the schema as 'Database ID', but workspace_id is undocumented in both places and the description never clarifies whether the ID is globally unique or workspace-scoped, nor whether passing workspace_id changes 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?

The description names the resource and enumerates the specific fields returned (engine, version, name, memory, address, port), which implicitly distinguishes it from siblings like get_database_status and get_database_metrics that report live state. It never coordinates with those siblings explicitly, but an agent can tell this is a metadata/config fetch rather than a health or metrics read.

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: 'Details of a database' signals a read on a known ID, with no statement of when to prefer it over get_database_status, get_database_metrics, or get_connection_info (whose address/port content overlaps). No prerequisites or exclusions 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful permission scope ('databases:read'), but does not disclose return format, time granularity, or whether results are paginated.

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 front-loaded sentence with no filler, followed by a concise scope note. It is appropriately sized for a metrics retrieval tool, though the phrasing is slightly noun-heavy rather than verb-led.

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 read-only metrics tool with no output schema, the description establishes the metric dimensions but omits the returned data shape, default time range behavior, and the purpose of the workspace_id parameter. It is adequate but leaves meaningful gaps that the schema does not fill.

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 only 33%: 'id' is documented, but 'range' and 'workspace_id' have no descriptions. The tool description adds no meaning for these parameters, such as how 'range' affects granularity or why 'workspace_id' might be needed.

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

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

The description clearly states that this returns historical CPU, RAM, storage, and network usage for a database, which is a specific resource and metric set. It does not explicitly distinguish itself from the sibling get_metrics tool, which likely covers app metrics, 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 word 'History' implies this is for retrieving historical metric data, but the description gives no explicit guidance on when to use it versus get_metrics, get_database_status, or get_database. No alternatives or exclusions 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is covered. The description adds the required scope (`databases:read`) and the live status fields, but does not discuss rate limits, return shape, or authorization failures beyond the scope label.

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 the core behavior front-loaded and the scope appended. Every clause carries useful information, including the optional-id behavior.

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

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

For a read-only status tool with no output schema, the description names the key status fields and explains the all-databases case, which is enough to call it correctly. The main remaining gap is the undocumented `workspace_id` parameter.

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 50%: `id` is documented in the schema, and the description adds meaningful semantics by explaining that omitting it returns all databases. `workspace_id` remains undocumented in both the schema and the description, leaving a clear gap.

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/resource combination, "Live status ... of a database," and enumerates the returned status fields (CPU, RAM, disk, uptime). It also clarifies the no-id behavior, though it does not explicitly distinguish itself from nearby siblings such as get_database_metrics or list_databases.

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 one useful usage rule: without `id`, it returns status for all databases. It does not state when to prefer this tool over get_database, get_database_metrics, or list_databases, so the agent must infer the distinction from 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful auth context with '(scope: apps:read)', but says nothing about behavior when no webhook is configured or what 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?

A single compact sentence plus a parenthetical scope tag — front-loaded and waste-free. It is arguably over-terse rather than bloated, so it loses a point only for insufficient substance, not verbosity.

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 getter with annotations covering safety and no output schema, the essentials are present. Still missing are what happens when no webhook exists and any hint about the undocumented workspace_id parameter.

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 only 50%: 'id' is documented as 'Application ID' but 'workspace_id' is undocumented in both schema and description. The description adds no parameter meaning at all, leaving the second parameter ambiguous for a scoped tool.

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

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

The description names a specific resource (the automatic-deploy webhook URL) for an application, which an agent can distinguish from siblings like create_deploy_webhook or delete_deploy_webhook. However, it is a noun phrase rather than a stated action ('retrieve the URL'), so the verb must be inferred from the tool name.

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