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

Annotations already indicate a mutating but idempotent, non-destructive operation. The description adds useful behavioral context: the inviting account must match the email, and the membership is tied to the account owning the key. This goes beyond what annotations and schema state.

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

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

Two sentences plus a scope note, with no filler. The core action is stated first, and the email restriction is a valuable additional detail. Every sentence earns its place.

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

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

For a single-parameter, mutation tool with no output schema, the description and schema together are sufficient: the action, the account/email binding, the token source, and the idempotent/non-destructive nature are all covered.

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

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

The input schema already fully describes the token parameter as the final part of the link, with 100% coverage. The description does not add further parameter meaning, 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 uses a specific verb and resource: 'Accepts an invite and joins the workspace.' This clearly separates it from sibling invite tools like preview_workspace_invite, decline_workspace_invite, and revoke_workspace_invite.

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

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

It provides clear context: accepting an invite joins the workspace with the account that owns the key, and email invites are restricted to that account's email. It does not explicitly name alternatives or state when not to use the tool, but the context is sufficiently clear for 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 carry the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and the description does not contradict them, so no annotation contradiction. The description adds the scope requirement (workspaces:write) as behavioral context, but does not disclose what 'moving' does to the app's prior location, existing visibility, or workspace members — useful context an idempotent write tool could 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?

One sentence plus a scope parenthetical; the verb and resource are front-loaded and every word earns its place. No redundant restatement of the tool name or schema fields.

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 tool with no output schema and no nested objects, the bar is modest, and the description covers the basic action. Still, it is missing key context: the 'move' semantics are ambiguous (the name implies add, the description implies relocation), and there is no pointer to the inverse operation (remove_app_from_workspace) or related publish/unpublish lifecycle 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 50%: the 'id' parameter is documented as 'Workspace ID', but 'app_id' has no description. The tool description does not compensate — it never mentions either parameter or clarifies the format/meaning of app_id beyond the vague 'application' noun. At 50% coverage the description should have stepped in, and it didn't.

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

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

The description uses a specific verb ('Moves') with a specific resource ('an application into the workspace'), which is understandable and distinguishable from siblings like remove_app_from_workspace and add_database_to_workspace. However, it doesn't explicitly name any sibling, and there is verb friction with the tool name — the tool is called 'add' but the description says 'moves' — without clarifying what 'moving' entails (from where, with what side effects).

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 is given about when to use this tool versus alternatives such as publish_app, unpublish_app, or remove_app_from_workspace. The parenthetical '(scope: workspaces:write)' communicates a permission requirement but provides no selection context or exclusion criteria.

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 idempotency (idempotentHint=true) and non-destructiveness (destructiveHint=false). The description adds the permission scope (workspaces:write), which is valuable behavioral context beyond annotations. However, it doesn't mention side effects like whether the database becomes unavailable from its previous location or any constraints, so it's adequate but limited.

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 sentence plus a scope parenthetical, very efficient and front-loaded with purpose. It contains no fluff, though it may be too terse for the missing parameter context. The structure is clear and scannable.

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

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

For a two-parameter write operation with a missing database_id description and no output schema, the description is incomplete. It lacks usage context, prerequisites, side effects, and parameter semantics. Annotations cover safety but not the operational details an agent needs to confidently invoke the 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 50%: only 'id' has a description ('Workspace ID'), while 'database_id' is undocumented. The description 'Moves a database into the workspace' implies database_id is the database to move, but it doesn't compensate for the missing schema description, nor does it clarify the relationship or required format. This leaves the agent relying on inference.

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 'Moves a database into the workspace' specifies a clear verb, resource, and destination, distinguishing it from siblings like remove_database_from_workspace and add_app_to_workspace. However, 'moves' could imply relocation from a specific source, which isn't clarified, so it's clear but slightly ambiguous.

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 is provided on when to use this tool versus alternatives. It doesn't mention whether the database must not already be in another workspace, what happens if it is, or contrast with add_app_to_workspace. The only extra info is the scope note, which is a permission requirement, 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 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 key behavioral trait that 'nothing runs until a person approves it in the dashboard' is disclosed, which is beyond what annotations provide (non-read-only, non-idempotent, non-destructive). The scope note '(scope: workspaces:write)' adds auth context. Together with annotations, the agent fully understands the request-approval lifecycle.

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

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

Two concise sentences, front-loaded with the core concept and gating behavior. No wasted words, and the scope is appended 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 4-parameter tool with a clear schema and no output schema, the description explains the purpose, the approval flow, and scope adequately. It could mention how requests are tracked, but the sibling list_action_requests implies that mechanism, so nothing critical is missing.

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

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

Schema description coverage is 75%, with id, resource_id, and snapshot_id already documented. The description adds no parameter-level details, and the 'action' enum provides its own semantics. Baseline 3 is appropriate because 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?

The description clearly identifies the tool's role as creating an approval request, distinct from executing the action directly. It states a specific behavior ('asks whoever has the permission') and clarifies that the request itself is not the execution, which distinguishes it from every direct-action sibling like delete_app or snapshot_restore.

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' gives clear context for when to use this tool: when the account lacks permission to perform the action directly. It also implies it is a fallback or escalation path, which differentiates it from direct-action siblings. It does not explicitly name an alternative or list exclusions, but the context is sufficiently explicit.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds useful context about the compression and ignored folders (node_modules, .git, .vertraignore) and mentions the scope apps:write. However, it does not disclose side effects like whether an existing app is overwritten, the asynchronous nature, or what the return value indicates. It adds some value beyond annotations but not comprehensive.

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 purpose and includes a parenthetical for clarity. Every phrase contributes value, and there is no wasted text. It is appropriately sized for a straightforward creation tool.

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

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

The tool has 9 parameters (4 required), no output schema, and many siblings. The description only provides a high-level summary without explaining expected outcomes, error conditions, or the creation flow after upload. An agent lacks information on how to verify success, what the response contains, or any prerequisites like folder existence. This is insufficient for a complex creation operation.

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

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

Schema description coverage is 67%, and the description does not elaborate on any parameter. It does not explain subdomain, description, or workspace_id, which lack schema descriptions. The description adds no parameter-specific semantics beyond what the schema provides, so it meets the baseline of 3 for high coverage but does not compensate for the gaps.

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: 'Creates an application from a folder' and details the process (compress, ignore specific folders, upload). It is specific about the resource (application) and the source (folder). It distinguishes itself from siblings like start_app or deploy_app by focusing on creation.

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 alternatives. It does not mention prerequisites, exclusions, or contrast with other app-related tools like update_app_config or deploy_app. The agent must infer that this is for new app creation from a folder, but there is no explicit instruction.

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 readOnly=false, idempotent=false, and destructive=false. The description adds a specific auth scope ('scope: databases:write') and the 'managed' qualifier, which provides a small amount of behavioral context. However, it does not disclose provisioning time, cost implications, or what happens when created.

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 with a parenthetical scope note, front-loaded and free of fluff. It is appropriately brief, though the brevity contributes to content gaps captured in other dimensions.

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

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

This is a 5-parameter create operation with no output schema. The description omits return value behavior, required parameter semantics, workspace_id relevance, and any post-creation status or provisioning behavior. It is far from sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is only 20% (only 'ram' is described), and the description does not compensate at all. It fails to mention engine choices, name constraints, description, or workspace_id, leaving agents without semantic guidance for most parameters.

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

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

The description states a clear action and resource: 'Creates a managed database.' This distinguishes it from database lifecycle siblings like list_databases, update_database, and delete_database. However, it adds little beyond the tool name and does not explicitly differentiate from other create_* tools beyond the resource type.

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 is given on when to use this tool versus alternatives, no prerequisites are mentioned, and there is no context about workspace requirements or follow-up steps. The description simply states the operation without any situational or selection 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds the scope requirement ('apps:write') and the 'renews' behavior, which is useful. However, it doesn't disclose what happens on renewal (e.g., whether the existing webhook is replaced), rate limits, or side effects beyond creation. No contradiction with annotations.

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

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

A single sentence that front-loads the action, includes the renewal nuance, and adds the scope requirement. No wasted words.

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

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

For a creation tool with no output schema, the description is adequate but leaves some gaps: it doesn't state what the response contains (e.g., webhook URL, secret) or whether the webhook is immediately active. The scope note helps, but an agent might need to infer the exact effect of 'renews'.

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 83%, so the schema already documents most parameters. The description adds the context that the repository must be 'already connected' and that the webhook is for the application, but it doesn't explain how parameters like repo_id and account_id relate to the GitHub App installation. Baseline 3 is appropriate since the schema carries most of the burden.

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 ('Creates (or renews)') and resource ('automatic-deploy webhook'), and clarifies the prerequisite ('from an already connected GitHub repository'). It distinguishes from siblings like get_deploy_webhook and delete_deploy_webhook by focusing on creation/renewal, though it doesn't explicitly name them.

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

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

The description implies when to use it: when the app needs an automatic-deploy webhook and a GitHub repository is already connected. It doesn't explicitly state when not to use it or name alternatives like get_deploy_webhook/delete_deploy_webhook, but the context is clear enough for an agent to select 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 indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description doesn't need to restate those. The description adds value by disclosing that the tool returns the final price with coupon discount and the order_id, and it notes the billing:write scope, which implies a mutating, permission-sensitive operation. It doesn't contradict annotations.

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

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

The description is a single, focused sentence that front-loads the action and resource, then states the return values. It includes the scope in parentheses without extra fluff. Every part 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 no output schema, the description adequately covers the return values (final price and order_id). The annotations cover safety and idempotency. It could mention what happens on failure or whether the order is immediately active, but the core information an agent needs to call it correctly is present.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (plan, coupon, months). The description adds context about coupon discount and final price, which relates to the coupon parameter, but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'creates', the resource 'plan subscription order', and the key outputs: final price with coupon discount and order_id. It also includes the scope (billing:write), which distinguishes it from other order-related tools like get_order_status and list_orders.

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 creating a plan subscription order and mentions the scope billing:write, which signals when it's appropriate. It doesn't explicitly name alternatives or exclusions, but the sibling list includes get_order_status and list_orders, and the description's focus on creation is clear enough 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 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, non-idempotent, and non-destructive. The description adds a permission scope ('scope: workspaces:write'), which provides useful auth context. However, it does not disclose side effects, error cases, or whether the role is immediately active.

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 brief and front-loaded, with no redundant wording. The parenthetical adds useful scope information. Its brevity is efficient, though it borders on under-specification, which is already penalized in other dimensions.

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 four parameters (three required), no output schema, and sparse annotations, the description is too thin. It omits what the 'permissions' array should contain, what 'position' means, and any expectation about the created role. An agent would likely need to guess or consult supplementary docs.

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% (only 'id' has a description), and the description adds no explanation for 'name', 'position', or 'permissions'. With low schema coverage, the description was required to compensate but does not, leaving these parameters semantically opaque.

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 ('Creates') and resource ('a role in the workspace'), which clearly identifies the core action. It is distinct from sibling tools like list_roles, update_role, and delete_role by the action verb, but it does not explicitly describe what a role is or how it differs beyond the 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?

There is no guidance on when to use this tool versus alternatives such as list_roles or update_role, no prerequisites like workspace existence, and no mention of cases where creation would not be appropriate. The agent must rely entirely on the tool name and context.

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

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

Annotations already mark it as non-read-only and non-destructive. The description adds valuable behavioral context beyond annotations: the action counts against a plan quota and requires the snapshots:write permission scope. No contradictions with annotations.

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

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

The description is two compact statements with no filler, front-loading the primary action before the quota warning and permission note. Every clause adds useful information.

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

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

For a two-parameter, low-complexity snapshot action, the required parameters are fully schema-documented and the description adds quota and permission context. It does not describe the return value or synchronous/asynchronous behavior, but there is no output schema and the core invocation is well covered.

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 scope and resource_id adequately. The description adds no new parameter details; the parenthetical '(scope: snapshots:write)' can be slightly ambiguous because it echoes the parameter name 'scope,' though the schema's enum disambiguates it.

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

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

The description uses a specific verb and object: 'Takes a snapshot of the resource,' making the core action clear. It names a distinguishing consequence (quota) and permission, but it does not explicitly contrast with sibling snapshot tools like list_snapshots or restore_snapshot.

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: call this when you need to create a snapshot and should be aware it consumes quota. It stops short of explicitly saying when not to use it or naming alternatives, so it does not reach the high-water mark of an explicit routing statement.

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 provide destructiveHint=true and idempotentHint=false. The description adds valuable context: the invite becomes invalid (permanent effect) and the action does not join the workspace. This goes beyond the annotations and helps the agent understand the side effects.

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

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

The description is a single, efficient sentence with no waste. The key action and consequence are front-loaded, and the scope note adds useful context without bloat.

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

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

For a tool with one required parameter, no output schema, and annotations covering safety, the description is complete. It explains what happens (invite becomes invalid) and what does NOT happen (no workspace join), which is all an agent needs to invoke it correctly.

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

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

Schema coverage is 100% and the token parameter is fully described in the schema as 'Invite token (the final part of the link)'. The description adds no additional meaning about the parameter, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Declines') and resource ('workspace invite'), and clarifies the outcome ('without joining the workspace; the invite stops being valid'). This clearly distinguishes it from accept_workspace_invite and gives the agent a precise understanding of the action.

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

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

The description implies the intended use (declining an invite you don't want to accept) by noting 'without joining the workspace'. However, it doesn't explicitly name alternatives like accept_workspace_invite or revoke_workspace_invite, nor does it state when NOT to use it. The context is clear but not explicit.

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 include destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the description does not need to restate these. It adds specific context that the deletion includes files and configuration, and explicitly says 'permanently', reinforcing irreversibility. This goes beyond the bare destructive hint and helps the agent understand the full impact.

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 delivers the core action and scope without any unnecessary words. It is front-loaded with the verb and resource, making it easy to parse quickly. The parenthetical scope note adds value without bloating the text.

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

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

For a destructive operation with two parameters (one required) and no output schema, the description covers the purpose, the extent of deletion, and the permission scope. It could mention the response or any prerequisites (e.g., app must be stopped), but these are not essential given the annotations and schema. Overall, it is sufficiently complete for an agent to invoke correctly.

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

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

The schema description coverage is 100%: both 'id' and 'workspace_id' have clear descriptions in the schema. The description itself does not add additional parameter-specific guidance, which is acceptable given the high coverage. It does not contradict the schema and meets the baseline expectation.

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

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

The description clearly states the action (permanently deletes), the resource (the application), and what is included (files and configuration). It also includes a scope annotation (apps:delete) that clarifies permissions. This distinguishes it from sibling tools like delete_workspace or delete_database because the resource is explicitly named.

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 stop_app, unpublish_app, or remove_app_from_workspace. The description only states what it does, not when it should be chosen. It does not mention exclusions or conditions, leaving the agent to infer usage from 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 and readOnlyHint=false, but the description adds valuable context: 'permanently' signals irreversibility, and 'along with the data inside it' specifies exactly what is destroyed. It also includes the scope string, providing an additional behavioral token. This goes beyond the structured annotations without contradicting them.

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

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

The description is a single, front-loaded sentence that immediately states the core action ('Permanently deletes'). The parenthetical scope adds a concise, non-redundant detail. Every word earns its place, with no filler 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 destructive delete tool with annotations covering safety, the description adequately conveys irreversibility and the full scope of data loss. It does not explain workspace_id, and there is no output schema to define return behavior, but these are minor given the simplicity of the operation and existing annotation coverage.

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

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

Schema coverage is 50%: id has a description ('Database ID') but workspace_id does not. The description adds no parameter-level meaning, and notably fails to clarify the purpose of workspace_id or when it should be provided. Since coverage is not high, the description was expected to compensate, but it does not address parameters at all.

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: 'Permanently deletes the database, along with the data inside it.' This clearly distinguishes it from sibling tools like stop_database or reset_database, which do not remove the database itself. The scope annotation '(scope: databases:delete)' further reinforces the exact action.

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

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

The description implies usage when permanent deletion is desired, but it does not explicitly contrast it with alternatives such as stop_database, reset_database, or delete_workspace. There is no 'use this when...' guidance or exclusion of other tools, leaving the agent to infer the appropriate context from the verb.

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

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

Annotations already mark the tool as destructive and not read-only. The description adds the concrete behavioral detail that anyone using the webhook URL loses deploy ability, which is valuable context beyond the annotations.

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

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

The description is a single, front-loaded sentence that states the action and its consequence, followed by a concise scope note. There is no wasted wording 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 delete operation, the description covers the purpose, the behavioral consequence, and the required scope. It does not explain the return value or the optional workspace_id, but the annotations and absence of an output schema keep the missing information minor.

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 provides no parameter-specific information; it does not mention 'id' or 'workspace_id'. The schema documents only 'id' as 'Application ID', leaving 'workspace_id' with no description, and the tool description does not compensate for that 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 the specific action 'Removes' and the resource 'automatic-deploy webhook', and it explains the consequence that the URL no longer enables deploys. This clearly distinguishes it from siblings like create_deploy_webhook and get_deploy_webhook.

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 clearly implies this tool is for removing an existing automatic-deploy webhook and states the required scope (apps:write). It does not explicitly name alternatives or exclusions, but the usage context is unambiguous and needs little inference.

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

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

The destructiveHint annotation already flags mutation/destruction, and the description aligns by naming the target (an environment variable). It adds a little context with the 'apps:envs' scope hint, but does not disclose consequences such as impact on running apps or reversibility, which would be more valuable.

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

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

The description is a single sentence with a compact scope note and no filler. It front-loads the operation before the procedural hint, though the parenthetical scope notation is terse and could be mistaken for an endpoint path.

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 delete tool with a destructive annotation and no output schema, it covers the core operation and how to obtain the variable ID. It is incomplete in that it never clarifies the relationship between the list_envs ID and the required id/env_id fields, and the optional workspace_id is left unexplained.

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

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

The schema covers id and env_id (67%), and the description adds the useful provenance hint that the variable ID comes from list_envs. However, the phrase 'variable id' does not explicitly map to the env_id parameter and workspace_id remains undocumented, so it only partially clarifies the schema.

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

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

The description opens with a specific action and resource ('Deletes an environment variable'), which distinguishes it from sibling tools like list_envs and set_env. It does not explicitly contrast with those siblings, and the follow-up instruction about 'variable id' introduces slight ambiguity, so it falls just short of a perfect score.

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

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

It gives a useful prerequisite: obtain the variable identifier from list_envs before deleting. However, it does not state when to choose this tool over alternatives, nor does it mention that set_env is the add/update counterpart or that deletion is irreversible.

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 adds the application-scoped context and clarifies the target is a file or folder, but it does not disclose recursion behavior, permanence, permissions, or whether the action is reversible. This is modest added value beyond the annotations.

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

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

The description is a single sentence with no filler, action verb first, and a useful scope parenthetical. Every word contributes to identifying the tool's core 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 destructive tool with no output schema and two undocumented parameters, the description is too thin. It states what is deleted but not how parameters map to the target, whether folder deletion is recursive, or any safety-relevant effects beyond the annotation-level destructive hint. An agent would need to open the schema and still may not understand path semantics.

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%: only 'id' has a description, while 'path' and 'workspace_id' are undocumented. The description provides no parameter-level information, so an agent cannot determine what the 'path' should refer to, whether it is app-relative, or how 'id' and 'path' interact. With low schema coverage, the description was expected to compensate but does not.

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

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

The description uses a specific verb ('Deletes') with a clear resource ('a file or folder') and adds an explicit scope ('apps:files'). This makes the tool's purpose unambiguous and differentiates it from the many other delete_* siblings, which target workspaces, databases, roles, etc.

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 such as move_file, write_file, or the many other delete_* tools. The only implicit usage signal is the phrase 'file or folder,' but no exclusions, prerequisites, or alternative recommendations are provided.

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 readOnlyHint=false. The description adds value by specifying the precise impact on users (loss of permissions) and the required scope (workspaces:write). This goes beyond the annotations and helps the agent anticipate side effects. No contradiction with annotations.

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

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

The description is one short sentence with a parenthetical scope note. It is front-loaded with the primary action and consequence, with zero wasted words. Ideal length for a simple delete 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 two-parameter delete tool with annotations covering destructive behavior, the description is nearly complete. It states the consequence on permissions and the required scope, which covers most operational context. Minor omissions like irreversibility are already implied by destructiveHint, so no significant gaps remain.

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% (only the 'id' parameter has a description, 'role_id' does not). The description provides no additional parameter details, so it fails to compensate for the undocumented 'role_id'. An agent is left to infer that role_id identifies the role to delete, but the description does not clarify the relationship or format.

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 (Deletes), the resource (a role from the workspace), and the key consequence (whoever had it loses those permissions). This distinguishes it from sibling tools like create_role, update_role, and delete_workspace without requiring 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?

The description implies its usage context: when you need to remove a role from a workspace. It does not explicitly name alternatives or state when not to use it, but the destructive nature and consequence make the intended use clear. A small gap is the lack of explicit routing to update_role for modifying rather than deleting.

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 significant behavioral detail beyond the annotations: it explains exactly what is destroyed (members, roles, invites, links) and what happens to apps/databases (return to owning account), and explicitly states irreversibility. This goes beyond the destructiveHint annotation's simple flag.

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 core action, followed by consequences and irreversibility. No filler words; the scope note is parenthetical and relevant.

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, no-output-schema destructive tool, the description fully covers the purpose, permissions, side effects, and irreversibility. An agent has enough to decide when to call it and what to expect, even without explicit alternative routing.

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

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

The input schema already covers the id parameter fully with 100% description coverage, so the baseline is 3. The description does not add any additional syntax, format, or constraints beyond 'Workspace ID', so it does not exceed the schema's explanation.

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 the action explicitly ('Deletes the workspace') with the resource and a permission restriction ('owner only'). It clearly distinguishes this from sibling delete tools like delete_app or delete_database by naming the workspace as the target, and the irreversible consequence reinforces its scope.

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 clear context for when to use: to permanently remove a workspace. It includes a prerequisite ('owner only') and describes the full consequences, which implicitly tells agents to use this only when they intend to delete the whole workspace rather than individual resources. It does not explicitly name alternatives but gives enough context to avoid confusion.

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 already indicate this is a mutating operation (readOnlyHint=false) and not idempotent. The description adds that it creates a 'new deploy' and uses the same compression criteria as `create_app`, which is helpful context. However, it does not disclose side effects such as the default restart behavior or what happens to previous deployments, so it goes only slightly beyond the annotations.

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

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

A single, front-loaded sentence states the core action, target, deployment type, and a relevant comparison. The trailing scope annotation is compact and useful. No filler or redundant restatement of schema properties.

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 plus schema covers the essential calling requirements for a straightforward deployment operation. There is no output schema, so a note about return behavior could have helped, and behavior around `restart` and previous deployments is not addressed. Overall it is adequate but not fully complete.

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

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

The schema already provides descriptions for 3 of 4 parameters (`id`, `path`, `restart`), giving 75% coverage. The description reinforces that `path` is a local computer folder and that `id` refers to an existing application, and adds the compression-criteria detail. It does not clarify the undocumented `workspace_id`, so it does not fully compensate for that 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 begins with a concrete action and target: 'Uploads a folder from the computer to an existing application (new deploy)'. It distinguishes itself from create_app by emphasizing 'existing application' and 'new deploy', and the scope annotation 'apps:files' adds further specificity. This is far more informative than a tautological restatement.

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 makes the use case clear: deploying a local folder to an already-existing application as a new deployment. It references `create_app` for compression criteria, giving a useful comparison point. It does not explicitly state when to avoid this tool in favor of `upload_files` or `create_app`, but the intended context is evident.

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 non-destructive behavior. The description adds useful behavioral detail: the tool creates a zip file locally at the specified destination. It does not mention overwrite behavior or authentication requirements, but the annotation coverage lowers the burden.

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 sentence with no filler. The core behavior is front-loaded, and the scope note is appended cleanly without disrupting 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 simple download operation, the description and schema give an agent enough information to invoke the tool correctly: target resource, destination path, and optional workspace. It does not describe the return value, but no output schema exists and the primary side effect is clearly stated.

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

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

Schema coverage is 100%, so the input schema already documents id, dest, and workspace_id. The description adds no semantic detail beyond what the schema 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 clearly states the specific verb and resource: it downloads the application's files as a zip and writes them to a given path. This differentiates it from siblings like download_snapshot and get_app, and the scope annotation adds useful 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 makes the tool's purpose obvious but gives no explicit guidance on when to prefer it over alternatives, such as download_snapshot. It neither states exclusions nor names sibling tools for comparison, leaving usage context implicit.

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. The description adds that the tool writes to a local path, which is not captured in annotations. However, it omits overwrite behavior, permission details beyond scope, and any side effects.

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

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

A single sentence plus a short scope note. The core action is front-loaded and there is no redundant or unnecessary text.

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

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

No output schema exists; annotations cover safety. The description covers the core action but lacks operational context such as file overwrite behavior, how to obtain a snapshot_id, or interaction with list_snapshots. Adequate for a simple tool but with 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 description coverage is 75%, with snapshot_id lacking a description. The description adds no parameter meaning beyond what schema already provides; it only restates the dest concept. No clarification of how snapshot_id relates to resource_id or how to obtain valid values.

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

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

States a specific verb 'downloads' with resource 'snapshot' and local destination, clearly distinguishing from siblings like restore_snapshot or list_snapshots. The description unambiguously conveys the 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?

No guidance on when to use this tool versus alternatives such as restore_snapshot or create_snapshot. The scope note is a permission hint, not usage context. It does not mention prerequisites like obtaining a snapshot_id from list_snapshots.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scope requirement (apps:read) and the specific fields returned, which is useful but does not disclose behavior like 404 handling, whether workspace_id is required for access, or response shape. No contradiction with annotations.

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

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

The description is a single compact sentence that front-loads the resource and fields, with the scope note appended. It is efficient and free of filler, though the scope parenthetical could arguably be moved to annotations or usage guidance.

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 detail tool with full schema coverage and safety annotations, the description is mostly adequate. However, it lacks guidance on when to use this versus get_app_status, and does not mention whether workspace_id is needed for cross-workspace access or what happens if the app is not found. These are minor gaps given the tool's simplicity.

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

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

Schema description coverage is 100%, so both parameters (id and workspace_id) are already documented in the schema. The description adds no additional parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a clear verb-resource pair ('Details of an application') and enumerates the specific fields returned (name, memory, runtime, main file, publication). It distinguishes itself from siblings like get_app_status and list_apps by focusing on full application details, though it does not explicitly name those 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 description implies usage context: it is a read-only detail lookup for a single application, and the scope annotation (apps:read) hints at permission requirements. However, it does not explicitly state when to prefer this over get_app_status, list_apps, or get_logs, nor does it mention any exclusions or alternatives.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful detail beyond that: the return payload ('CPU, RAM, uptime'), the all-applications default, 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?

A single sentence delivers the core resource, the concrete fields returned, the conditional behavior, and the permission scope. There is no filler or redundancy.

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

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

For a simple read-only tool with only two documented parameters, the description plus schema fully covers what the agent needs: what to pass, what comes back, and the scope. The annotations handle the safety semantics, so no further caveats are required.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning to the optional 'id' parameter by explaining that its absence returns status for all applications, going beyond the schema's bare 'Application ID' label.

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

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

The description names a specific verb and resource ('get app status') and concretely defines the output (CPU, RAM, uptime). It also distinguishes the no-id behavior ('of all of them'), distinguishing it from related tools like get_app or list_apps.

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 makes the device clear: call with an id for a single application, or omit id for all applications. It also states the permission scope ('apps:read'). It does not explicitly name alternative tools, but the conditional id behavior gives sufficient usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: the server does not execute queries, the CA certificate is in PEM format, and the connection string is only present when the account has one. This goes beyond the annotations without contradicting them.

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

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

The description is two tight sentences. It front-loads the returned data, then adds a caveat and a scope note, with no filler or redundant repetition of the schema.

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

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

With no output schema, the description usefully enumerates the returned fields and the non-query behavior, which is good for a read-only credential tool. However, it leaves parameter semantics, especially workspace_id, unexplained and provides no sibling-selection guidance, so it is not fully self-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?

The schema describes 'id' as Database ID but leaves workspace_id undocumented, and schema description coverage is only 50%. The description does not mention either parameter or clarify the role or requirement of workspace_id, so it fails to compensate for the 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 clearly identifies the resource (database) and the specific payload (address, port, engine, CA certificate, connection string), making the tool's purpose unmistakable. It does not use an explicit verb like 'retrieves' or name a sibling tool to distinguish from, but the connection-data focus separates it from get_database and get_database_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?

There is no explicit guidance on when to use this tool versus alternatives such as get_database, get_database_status, or reset_credentials. The statement that the server does not run queries explains behavior but does not help an agent choose among the many database-related sibling 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 the safety profile is covered. The description adds the databases:read scope and the specific fields returned, but does not mention not-found behavior, errors, or relationship to status/metrics endpoints.

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 compact sentence with the core purpose front-loaded and the scope cleanly parenthesized. No filler or redundancy.

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

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

For a simple get-by-id read with strong annotations, the description covers the return fields and auth scope sufficiently. It is slightly incomplete because it doesn't explain workspace_id or distinguish from status/metrics/connection-info siblings, but an agent can still invoke it correctly.

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

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

Only id has a schema description ('Database ID'); workspace_id has none. The description does not explain either parameter or how workspace_id affects the lookup, so it fails to compensate for the 50% schema 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 resource (database) and specifies the return payload (engine, name, memory, address, port), so an agent knows this is a detail-read operation. It does not explicitly differentiate from sibling tools like get_database_status, get_database_metrics, or get_connection_info, though the field list hints at a general details view.

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 about when to choose get_database over the many sibling database tools (list_databases, get_database_status, get_database_metrics, get_connection_info). The 'databases:read' scope is an authorization hint, not a usage rule or alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat safety traits. It adds useful context about returning historical usage metrics and the required scope, but it does not mention response shape, pagination, or range behavior.

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 names the resource, the metric categories, and the permission scope. There is no filler or 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 simple read-only metrics tool, the core purpose and required id are clear, and annotations cover safety concerns. However, the optional params and the relationship to get_metrics are unexplained, leaving meaningful gaps in call correctness.

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

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

The input schema only describes the 'id' parameter, giving 33% schema description coverage. The description does not clarify 'range' or 'workspace_id', and while the range enum values are self-explanatory, the description fails to compensate for the low parameter documentation 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 clearly identifies the resource (database) and the data returned (historical CPU, RAM, storage, and network usage). It is not tautological and conveys more than the tool name alone, though it does not explicitly distinguish itself from the related sibling get_metrics.

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 get_metrics or get_database_status. The scope annotation 'databases:read' provides permission context but no decision support for choosing among sibling 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, covering safety. The description adds behavioral context beyond annotations by specifying the live metrics returned and the aggregation behavior when `id` is omitted. It omits response format details, but this is a read-only status 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?

A single tightly packed sentence that front-loads the core behavior, follows with the scoping condition, and appends the permission scope. Every word contributes value; no redundancy.

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

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

Given two optional parameters and no output schema, the description explains what data is returned (CPU, RAM, disk, uptime) and how the `id` parameter changes scope. Missing is an explanation of `workspace_id` and a more explicit return shape, but the essential invocation information is present.

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

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

Schema coverage is only 50%: `id` has a description, `workspace_id` has none. The description adds crucial meaning for `id` (omitting it means 'all of them'), which compensates partially, but it does not clarify the role of `workspace_id`. Thus it leaves one parameter unexplained.

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

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

The description clearly states the tool's function: returning live status (CPU, RAM, disk, uptime) of a database, and distinguishes scope: with `id` it targets one database, without `id` it targets all of them. This specificity differentiates it from siblings like get_database_metrics and get_app_status.

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

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

The description gives clear usage context: provide `id for a single database, omit it for all databases. However, it does not explicitly name alternative tools or state when not to use this tool, leaving some routing ambiguity among database-related siblings.

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, openWorldHint, and non-destructive behavior, so the safety profile is established. The description adds only that the result is the webhook URL but no additional behavioral context such as authentication needs, response shape, or side effects. There is no contradiction with annotations.

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

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

The description is compact, front-loaded, and contains no filler. It is under-specified as a fragment, but for what it says, it is concise.

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 get-by-ID operation with strong annotations, the description is nearly adequate: it identifies the returned resource as the webhook URL and the schema supplies the required id. However, the missing verb and the undocumented optional workspace_id leave a small but real gap in complete guidance for an agent deciding how to call it.

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

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

The schema documents only id with 'Application ID'; workspace_id has no description and the description offers no clarification. With 50% schema description coverage, the description needs to compensate for the undocumented parameter, but it does not.

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

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

The description is a noun phrase, not a statement of what the tool does. 'The application's automatic-deploy webhook URL' largely restates the tool name and lacks an action verb like 'retrieves' or 'gets', so it does not clearly distinguish the operation from sibling create/delete webhook 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?

No guidance is provided about when to use this tool versus create_deploy_webhook, delete_deploy_webhook, or other getters. There are no conditions, limitations, or alternative routing cues.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by stating that the tool is a knowledge base and that the optional `section` parameter trims an excerpt by title, which is not derivable from annotations alone.

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

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

The description is two sentences with no filler: the first states what the knowledge base contains, the second gives the key usage instruction and explains the parameter behavior. Every sentence earns its place and the most important guidance is front-loaded.

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

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

For a simple, optional-parameter, read-only documentation tool, the description is complete: it states the content domain, when to consult it, and how the section parameter affects the result. The annotations cover the safety profile, and no output schema is needed for this level of complexity.

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

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

Schema description coverage is 100%, so the schema already documents the single `section` parameter. The description adds semantic value by explaining how the parameter behaves ('trims an excerpt by title'), enriching the agent's understanding beyond the schema text.

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 identifies the tool as 'Vertra Cloud's public knowledge base' and enumerates its contents: plans, prices, limits, supported languages, and error codes. It also gives a specific instruction ('Consult it before stating any number'), which makes the purpose operational and distinguishes it from all sibling tools, none of which are documentation lookups.

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 a clear usage signal: consult this tool before stating any number. It does not explicitly name alternatives or give when-not-to-use conditions, but the context among mutating workspace/app/database tools makes the read-only documentation role obvious.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds only the 'full file tree' and 'apps:files' scope context, with no additional behavioral detail such as recursion, pagination, or missing-file behavior.

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 short and front-loaded, with the essential noun phrase first and the scope note appended. It is appropriately terse, though the parenthetical 'scope: apps:files' is somewhat 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 read-only tree tool with annotations covering safety, the description is minimally viable: an agent knows it will receive a full file tree. However, there is no output schema stub and no explanation of what tree nodes contain or how workspace_id affects results, leaving gaps for a 2-parameter 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?

The schema documents only 'id' as 'Application ID'; workspace_id has no schema description, and the tool description does not explain it or add meaning to either parameter. With 50% schema coverage and no compensation in the description, parameter semantics are weak.

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 identifies the resource as 'the application's full file tree' and adds a scope hint ('apps:files'), so an agent can tell it returns a tree of files rather than a single file or listing. It lacks an explicit verb and does not differentiate itself from sibling tools like list_files or read_file, which keeps it from a 5.

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

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

The description gives no guidance about when to use this tool versus alternatives such as list_files, read_file, or move_file. The scope note is helpful but does not state conditions, exclusions, or a preferred alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond those annotations: the log is a snapshot rather than real-time, and the `tail` parameter trims the last N lines of the API response. This helps the agent understand data freshness and parameter behavior.

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 sentences deliver the core purpose, the snapshot behavior, the tail semantics, and the scope. No filler or repetition; the most important information is front-loaded.

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

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

For a simple read-only log retrieval tool with full schema parameter coverage, the description is largely complete. It communicates the return concept (last log lines), the non-real-time caveat, and the scope. Without an output schema, it could still briefly mention the format of the returned log lines, but the current content lets an agent 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 coverage is 100%, so the baseline is 3. The description adds some meaning to the `tail` parameter by explaining it trims the last N lines of what the API returned, but it does not add meaningful semantics for `id` or `workspace_id` beyond the schema. The added tail detail is useful but modest.

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 identifies the resource (application logs) and the operation: returning the last lines of the log. It adds the meaningful qualifier 'snapshot, not real time,' which helps distinguish this from real-time log streaming, though it lacks an explicit verb like 'retrieve' or 'return.'

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 through the tool name and the phrase 'application's log,' and the snapshot/not-real-time note sets expectations. However, there is no explicit guidance about when to prefer this over sibling tools like get_app_status or get_metrics, and no mention of alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is already known. The description adds the useful context that the tool returns historical metrics rather than current values, and scopes it to app-level resources. It does not disclose response shape, pagination, or how the range parameter behaves, but the annotations lower the bar.

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, focused sentence with no filler, and the app scope is stated clearly. The phrase 'History of...' is compact but could be more explicit with a verb like 'Retrieves historical...'.

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 metrics tool, the description plus schema is mostly adequate. Missing context includes how the range parameter shapes the history, what the response contains, and when workspace_id is relevant. The lack of an output schema puts some burden on the description, which it only partially meets.

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 workspace_id described, and the range enum values are self-explanatory. The description clarifies what kind of metrics are involved, which helps interpret the id parameter, but it does not explain range values or when workspace_id is needed. This sits at the baseline where the schema does most of 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?

The description clearly identifies the resource (the application) and the metric types (CPU, RAM, storage, network). It is slightly weakened by lacking an explicit verb like 'retrieves', but 'History of' conveys the read intent. The application focus distinguishes it from similar siblings like get_database_metrics, even without naming them.

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

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

No guidance is given for when to use this tool versus alternatives, such as get_database_metrics or get_logs. The scope note '(scope: apps:read)' is an authorization context, not a selection criterion. There are no exclusions or 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=true, idempotentHint=true, and destructiveHint=false. The description adds the auth scope '(scope: apps:read)' and the behavioral detail 'in a single response', which informs the agent that domain and DNS records are returned together. This is valuable context beyond the annotations.

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

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

The description is a single efficient sentence followed by a short scope note. It front-loads the core purpose without redundant words, repetition, or filler.

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

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

The description covers the return content (custom domain and DNS records) but omits explanations for the optional workspace_id parameter and provides no error behavior. For a simple read tool with no output schema, it is mostly sufficient but has a notable gap for the undocumented 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?

The description does not mention either parameter. The input schema describes 'id' as 'Application ID' but leaves 'workspace_id' undocumented, and with only 50% schema coverage, the description should have compensated but doesn't. No additional meaning is added 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 identifies the specific resource (application's custom domain and DNS records) and implies the 'get' verb through the tool name. It distinguishes itself from siblings like set_custom_domain and get_app by specifying the exact data returned.

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 is provided about when to use this tool versus alternatives. There are no exclusions or references to sibling tools, leaving the agent to infer usage from the name and description alone. The scope note hints at read access but doesn't explicitly route the agent.

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 readOnlyHint=true and idempotentHint=true, but the description adds value by specifying the polling behavior and the condition of waiting until the order turns paid. It also includes a scope note. No contradiction with annotations; it enriches the operational understanding.

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

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

The description is extremely concise: one sentence plus a scope note. The core purpose is front-loaded, followed by a clear usage instruction. No wasted words; every segment earns its place.

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

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

For a simple status-check tool with one parameter and no output schema, the description is complete enough. It covers what the tool does, how to use it (polling), and the scope. It doesn't specify return values or error handling, but those are not mandated by the context. The sibling list_orders handles broader queries, so coverage is 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?

With schema coverage at 0%, the description carries the burden. It clearly implies that order_id is the identifier of the order whose status is being checked. Even though the schema only says 'string', the description effectively explains the parameter's purpose, making it understandable for an agent.

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

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

The description clearly states the tool's function: retrieving the status of an order. It implicitly differentiates from list_orders by focusing on a single order identified by order_id. The phrase 'Status of an order' is specific enough, though it lacks an explicit verb like 'retrieve' or 'get'.

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

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

It provides a clear usage pattern ('poll it periodically until it turns paid'), which tells the agent when to use it. However, it does not explicitly mention when not to use it or alternatives (e.g., list_orders for batch views). The scope note (billing:read) gives some context but not direct guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description doesn't need to restate those. The description adds useful behavioral context: it clarifies that the agent never pays, and that the tool returns both copy-and-paste code and QR Code. However, it doesn't disclose side effects like whether the payment is marked as pending, whether repeated calls create multiple PIX charges, or any rate limits. The scope (billing:write) is mentioned in the description, which adds context beyond annotations.

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

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

The description is concise and front-loaded with the main action. The parenthetical scope note is useful and doesn't waste words. The sentence about who pays is important behavioral context and earns its place. Slightly more structure could be added, but it's appropriately sized for a simple tool.

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

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

For a tool with one parameter and no output schema, the description covers the main purpose and a key behavioral constraint (agent never pays). However, it doesn't describe the return format beyond 'copy-and-paste code and QR Code', doesn't mention error conditions (e.g., invalid order_id, order not found), and doesn't clarify whether the PIX code expires or is single-use. Given the billing context, these details could matter for an agent deciding whether to call the 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 0%, so the description must compensate for the undocumented order_id parameter. The description mentions 'the order's PIX payment' which implies order_id refers to the order for which payment is generated, but it doesn't explicitly explain the parameter format, required format, or any constraints. With only one parameter and a clear name, the meaning is inferable, but the description doesn't add explicit parameter-level detail beyond what the schema shows.

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

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

The description clearly states the tool's function: generating the order's PIX payment and returning the copy-and-paste code and QR Code. It identifies the specific resource (order) and the action (generates PIX payment). It doesn't explicitly differentiate from siblings, but the PIX payment context is unique among the listed sibling tools, so the purpose is clear enough.

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 context: it is for generating a PIX payment for an order, and it explicitly notes that the person pays, not the agent. However, it doesn't explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like order status or payment state. The scope annotation (billing:write) provides some context but not explicit when-to-use 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 the tool read-only, idempotent, open-world, and non-destructive, so the description need not restate those. It adds the permission scope ('account:read') and the data categories, but does not disclose response shape, units, or freshness. This is acceptable given the strong annotations, but the description itself adds only modest behavioral context.

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

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

The description is a single compact line with no filler, tautology, or repeated schema information. The resource and its main content are front-loaded, and the scope note is appended cleanly.

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 zero parameters and rich safety annotations, the tool is straightforward to invoke. The description covers the main output categories, though a fuller response shape or units would help since there is no output schema. Still, nothing essential is missing for selecting and calling this 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?

The input schema has zero parameters, so there are no parameter semantics to explain; the rubric assigns a baseline of 4 in this case. The description adds value by naming what the profile contains, which is enough for an agent to understand the payload domain without needing parameter details.

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 concrete resource ('Account profile') and enumerates its key contents (plan, allocated memory, limits, usage), making the operation clear despite lacking an explicit verb. The scope note 'account:read' and the tool name also help distinguish it from account-mutating siblings like update_profile and from resource-specific getters like get_workspace or get_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?

No explicit guidance is provided about when to use this tool versus related read tools such as get_metrics, get_workspace, or get_order_status. The content list implies it is for account-level profile information, but there are no stated alternatives, exclusions, or 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only the scope note ('workspaces:read') and does not describe return format or potential errors. With annotations covering most behavioral aspects, a 3 is appropriate.

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 gets straight to the point. No filler or redundancy. It is appropriately sized for a simple read 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 one-parameter read-only tool with rich annotations (readOnly, idempotent, non-destructive), the description is sufficient. It does not explain return values, but no output schema exists and the tool is simple enough that an agent can infer the result. The description is complete enough 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?

The input schema has 100% coverage for the single 'id' parameter with a description 'Workspace ID'. The tool description does not add any additional meaning beyond the schema, so it meets the baseline for full schema coverage.

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

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

The description states the resource (workspace) and action (retrieve details) clearly, and the scope note adds context. It is distinguishable from list_workspaces which lists all workspaces. The verb 'Details' is slightly weak but still conveys the purpose unambiguously.

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

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

No explicit guidance on when to use this tool versus alternatives. The sibling list_workspaces implies a distinction (list vs. single details), but the description does not explicitly state 'use this for a specific workspace' or mention any exclusions. Usage is implied but not spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the scope constraint (workspaces:read) and clarifies that approval/rejection actions are not available through this tool, which is useful behavioral context beyond the annotations.

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

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

The description is two sentences with no wasted words. It front-loads the core purpose, then adds the critical behavioral constraint about dashboard-only approval/rejection, and ends with the scope annotation. Every sentence earns its place.

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

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

For a read-only listing tool with strong annotations (readOnlyHint, idempotentHint, destructiveHint), the description is largely complete. It could benefit from mentioning the return format or pagination, but the absence of an output schema and the simplicity of the tool make this 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?

Schema description coverage is 50%, with the 'id' parameter documented in the schema. The description doesn't add detail about the 'status' parameter, but the schema provides an enum for it. The description's mention of action request types adds some context but doesn't fully compensate for the undocumented status 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 clearly states the tool lists action requests for a workspace, enumerates the types of action requests (delete app/database, create/restore snapshot), and explicitly notes that approving/rejecting is dashboard-only. This distinguishes it from sibling tools like create_action_request and list_snapshots.

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 this is for viewing action requests and explicitly states that approving/rejecting is dashboard-only, which tells the agent not to attempt those actions here. It doesn't explicitly name alternatives, but the context is clear enough for a read-only listing tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful context by specifying the 'apps:read' scope and promising current status per app. It doesn't discuss pagination or output shape, but the annotation coverage reduces the burden.

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 concise sentence with no filler. The action, resource, output detail, and scope are all front-loaded and each word 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 no-parameter read-only listing tool, the description covers what is listed and what is included for each item. It doesn't specify return formatting or pagination, but the absence of an output schema and parameters makes this 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?

There are zero parameters and schema coverage is 100%, so the baseline is 4. The description has no parameter details to add, and the scope string supplies relevant authorization context.

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

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

The description uses a specific verb ('Lists') and a specific resource ('the account's applications') and adds the key output detail ('current status of each'). This clearly separates it from siblings like list_workspaces, list_databases, and get_app.

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

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

The intended context is clear: use this to enumerate applications belonging to the account. It doesn't explicitly name alternative tools or state when not to use it, but for a zero-parameter list tool the usage is evident enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the scope 'databases:read' and confirms that status is included in the result, but does not describe pagination, ordering, or the exact status values 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?

The description is a single, dense sentence followed by a scope indicator. It front-loads the core action and resource, adds the status detail, and contains 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 parameterless list tool with strong annotations, the description is sufficient. It tells the agent what will be listed and that status is included; no output schema exists, but the purpose and scope are fully clear for selecting and invoking the 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?

The input schema has no parameters, so the baseline is 4. The description adds no parameter information, but none is needed since calling this tool requires no arguments.

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 action ('Lists'), a clear resource ('the account's databases'), and an additional useful detail ('with the status of each'). It also includes the permission scope, making the tool's role immediately distinguishable from siblings like get_database or get_database_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?

The description clearly conveys the use case: to list all databases at the account level including their status. It does not explicitly name alternatives or exclusions, but for a list-all operation the context is straightforward and unlikely to be confused with singular database 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe and non-mutating. The description adds little behavioral context beyond the annotations; it doesn't clarify what 'deploy history' includes or how it relates to deploys, but it doesn't contradict 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 one short sentence, front-loading the main purpose. The scope note is appended in parentheses, which is concise and does not waste words.

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

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

Given the tool has a simple purpose and no output schema, the description is minimally sufficient. However, it lacks detail on required parameters (id) and whether workspace_id is needed, and it doesn't mention any pagination or filtering options that might be expected for a 'list' 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 50%, meaning the 'id' parameter is described as 'Application ID' in the schema, but the 'workspace_id' parameter is not described. The description provides no additional parameter meaning, so it doesn't compensate for the gap, but the schema provides the core meaning.

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 that this tool lists the application's deploy history, which is a clear verb-resource combination. However, it does not differentiate it from sibling tools like deploy_app or get_logs, and the scope note is minimal.

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 does not indicate when to use this tool versus alternatives, nor does it mention any required context such as the need for an app ID or workspace. The scope note (apps:read) is a signal but not explicit 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 establish read-only and non-destructive behavior, so the description adds value beyond them by revealing a key behavioral guarantee: values are never exposed by any tool, and the scope is apps:envs. This helps the agent avoid expecting secret values and rounds out the 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?

Two short sentences front-load the purpose and the critical non-disclosure caveat, with a compact scope annotation at the end. Every word earns its place and there is no redundant 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, safe, read-only enumeration tool, the description covers the core behavior, the non-disclosure guarantee, and the scope; annotations handle the safety profile. The main gap is that workspace_id remains unexplained, so an agent cannot be fully certain when it is required, but the overall tool is still callable with the documented id.

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

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

The schema documents id as 'Application ID', but workspace_id has no description and the description does not clarify it. With only 50% schema description coverage, the description needed to compensate for the undocumented parameter, but it only restates the app-level scope without explaining when workspace_id is 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 opening sentence names a specific operation ('Lists the NAMES') on a clear resource ('application's environment variables'), and immediately distinguishes itself from value-returning or mutating env tools by stating values are never returned. This is enough to separate it from set_env/delete_env 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 description clearly states when to use the tool: when you need the names of environment variables. It also gives a strong exclusion: values are never returned and no tool reads a variable's value, so the agent knows not to expect secrets. It does not explicitly name mutation alternatives like set_env/delete_env, but the guidance is otherwise 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 carry the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description does not need to repeat that. It adds a bit of scoping context but reveals no extra behavioral traits such as recursion, pagination, hidden-file handling, or path semantics.

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

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

The description is a single, front-loaded sentence with the scope in parentheses. Every part earns its place, and there is no wasted wording.

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 listing tool with rich annotations and partial schema coverage, the description is workable. However, the missing `workspace_id` semanticsermann and lack of any return/pagination details mean an agent must still infer some important behavior.

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

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

The schema already describes `id` and `path`, but `workspace_id` is undocumented and the description adds no parameter-level meaning. With 67% schema description coverage, the description could compensate for the missing parameter, but it does not.

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 ('Lists') and a specific resource ('files and folders of a directory'), with an application scope. However, it does not explicitly differentiate this from the sibling get_file_tree, which could also return directory contents, so it stops short of a 5.

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

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

No guidance is given on when to use this tool versus alternatives like get_file_tree or read_file. The parenthetical scope hint adds context but does not state exclusions, conditions, or which sibling tool should be selected instead.

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