AppDeploy

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

Annotations already cover readOnlyHint=false and destructiveHint=true. The description adds that this starts an async deployment process requiring status polling, and that the version must come from get_app_versions. This goes beyond the structured data without contradicting it.

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: two sentences that first state the purpose and then give the operational workflow. Every word earns its place, with no redundancy or fluff.

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 tool with no output schema, the description supplies the action, the expected source of the version, and how to monitor completion. It is not overly detailed but sufficient for the tool's complexity. Could mention error scenarios, but that is beyond requirements.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds semantic value by specifying that 'version' should be taken from get_app_versions, and that app_id refers to an existing app, which is not fully captured in the schema.

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

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

The description clearly states the action: 'Start deploying an existing app at a specific version.' This uses a specific verb and resource, and distinguishes from sibling tools like deploy_app by emphasizing 'former app version' and referencing get_app_versions and get_app_status for the full rollback workflow.

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 explicit steps: obtain the version from get_app_versions, then poll get_app_status until a terminal status. This gives clear contextual guidance, though it does not explicitly state when not to use the tool or name alternatives such as deploy_app for fresh deployments.

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

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

Annotations already indicate destructive intent, and the description adds valuable context by listing the lifecycle actions (add, verify, delete) and limiting scope to existing apps. It does not contradict the annotations and provides reasonable behavioral context beyond what the schema or annotations alone offer.

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 concise sentence that front-loads usage guidance and lists the core operations. 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 tool with four parameters, no output schema, and destructive potential, the description covers the essential purpose, scope, and actions. Combined with the parameter schema and annotations, an agent has enough information to select and invoke it correctly. Minor additional details (e.g., dns_mode requirement) are left to the schema, which is acceptable.

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 descriptions exist for all parameters. The tool description adds meaning by explaining that 'domain' is a hostname and clarifying the 'action' values (add, verify, delete). This exceeds the baseline for high 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 clearly states the tool manages a custom domain for an existing app and enumerates the specific actions (add hostname, verify DNS, delete). The verb 'manage' is broad, but the list of operations makes the purpose specific and distinguishes it from sibling tools like get_custom_domain_instructions.

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

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

The description explicitly says 'Use this when you need to manage a custom domain for an existing app', providing clear usage context. It does not mention alternatives or exclusions, but the sibling list shows get_custom_domain_instructions is for instructions, so the context is sufficient.

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

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

Beyond annotations (readOnlyHint: false, openWorldHint: true, idempotentHint: false), the description discloses that the link is one-time and pre-authorized, and provides client-side handling instructions (open in new tab, show raw URL in CLI). This adds useful behavioral context without contradicting 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 concise sentences, front-loaded with the primary purpose and followed by a practical usage instruction. Every sentence offers meaningful value with no redundancy.

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

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

For a simple create-link tool, the description covers purpose, input context, return URL, and client behavior. It does not mention how to check secret entry status (related sibling), but given no output schema and the simplicity of the tool, the description is sufficiently complete.

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

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

The input schema fully describes both parameters (app_id and secret_name) with clear descriptions, so the description does not need to add much. The description mentions the return value (secret_entry_url) but not parameter details, which is acceptable given 100% 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 action ('Create a one-time pre-authorized browser link') and the resource (a link for submitting a backend secret value). This clearly distinguishes it from sibling tools like set_app_secrets (direct setting) and get_secret_entry_status (status checking).

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 explains when to use the tool ('so the user can submit a backend secret value outside chat without an extra login step'), giving clear context. It does not explicitly mention alternatives or exclusions, but the context implies use cases where direct secret setting is not 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 indicate destructive and non-idempotent. The description adds the consequence of irreversibility and that status checks will return not found, providing 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?

Three short sentences, front-loaded with purpose, each sentence adds unique value without redundancy.

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

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

For a simple one-parameter destructive delete operation, the description covers purpose, usage condition, and irreversible consequence. No output schema means no return-value explanation needed.

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

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

The only parameter app_id is fully described in the schema as 'Target app id'. The description adds no param-specific details, but schema coverage is complete, so 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 tool deletes an app permanently, using a specific verb and resource. It distinguishes from sibling read/status tools and delete_app_secrets.

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

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

The description explicitly states when to use ('when you want to permanently delete an app') and adds a condition ('only on explicit user request'), providing clear 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 provide destructiveHint, idempotentHint, and openWorldHint. The description adds a specific behavioral trait: 'Missing names are ignored,' which clarifies the idempotent behavior beyond the annotation. It does not contradict annotations and adds useful context about handling non-existent secrets.

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

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

The description is a single, focused sentence that front-loads the action and object. Every word is necessary; it includes the important nuance about missing names being ignored without any 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 delete operation with two well-documented parameters and no output schema, the description covers the core behavior and edge case (missing names). It does not specify return values, but given the destructive and idempotent nature disclosed via annotations, this is sufficient. Missing only a brief note on expected output, but overall complete for its complexity.

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

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

The schema covers 100% of parameter descriptions, so baseline is 3. The description adds no new semantic meaning beyond what the schema already contains; it mirrors the schema's 'one or more' and 'backend secret names' phrasing without enriching it.

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

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

The description clearly states the action (delete) and the specific resource (backend secret names) with scope (from an existing app). It distinguishes itself from sibling tools like delete_app (deletes the entire app) and set_app_secrets (creates/updates secrets).

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 by naming the operation and target but does not explicitly state when to use this tool over alternatives (e.g., 'use set_app_secrets to add or update, this only deletes') or any preconditions beyond the app existing. No when-not guidance is 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?

Annotations already carry the safety profile (destructiveHint=true, readOnlyHint=false), and the description adds substantial behavioral context beyond them: diff replacement fails unless 'from' is unique or multiple=true, template files are auto-included as a baseline, certain packages are platform-injected, and repeated calls stop on lifetime-limit errors. No contradiction with annotations exists.

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

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

The description is well-structured and front-loads the most critical constraint (files[] must be a JSON array), but it is very long for a tool description. Peripheral code-style rules (never minify, prefer single quotes for JS/TS string literals) are code-generation preferences rather than invocation semantics and could be moved elsewhere. Still dense and purposeful overall.

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 15-parameter, two-mode tool with no output schema, the description covers nearly everything an agent needs: required parameter sets per mode, exclusions, constraint violations, error handling, polling cadence, and retry limits. The one gap is the deploy_app response value itself, though the polling instruction implies that status is obtained via get_app_status rather than the deploy response.

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, but the description adds real meaning beyond the schema by encoding combination rules the schema cannot express: which parameters are required for new apps vs updates, the mutual exclusivity of upload_id with files[]/deletePaths[], and the mandatory JSON-array shape for files[] with a concrete example.

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 states a specific verb (deploy/update), resource (website/web app), and outcome (get a public URL). It then splits the operation into new-app vs update modes, making the tool's single purpose — publish or refresh an app — unambiguous and clearly distinct from siblings like upload_assets or 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 explicit when/when-not guidance: use upload_assets for binary assets versus files[] for inline text, use diffs[] only for template files, and use either changed files/deletePaths or upload_id but never both. It also names sibling tools directly (get_app_template, get_app_status, upload_assets) and prescribes the exact post-deploy polling and retry protocol.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: dependency expansion details, the implementation-contract usage, and confirmation that it is a request for information. 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 front-loaded and clear but contains redundancy: 'Call get_appdeploy_sdk_reference once per top-level SDK feature' and 'Request one top-level SDK feature per call' are duplicative, and the dependency expansion is repeated in the schema. It is appropriately sized but not tightly written.

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

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

With a single enum parameter and read-only annotations, the description covers purpose, usage constraints, dependency expansion, and implementation-contract intent. No output schema exists, but the return types ('types, rules, examples') are described sufficiently for the tool's role.

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's feature parameter has extensive per-enum-value descriptions and scenario guidance, covering 100% of parameter semantics. The tool description largely duplicates the calling convention and dependency expansion already present in the schema, adding no additional parameter-specific meaning beyond the baseline.

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 returns types, rules, and examples for one requested SDK feature plus its dependencies, and frames it as an implementation contract. This distinguishes it from sibling read tools like get_app_template or get_deploy_instructions by its specific function.

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

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

Provides explicit calling conventions: one top-level feature per call, exactly one enum value, no separate dependency requests, and use the highest-level feature. It does not explicitly name alternatives or exclusions, but the contextual guidance is strong enough for an agent to know how to use it correctly.

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, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds the ownership scope ('owned by the current user') and the discovery purpose, but does not detail pagination or response format. This aligns with the bar for annotation-backed descriptions.

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

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

The description is two sentences, front-loaded with the main action and then usage guidance. No redundant or filler content.

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

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

For a simple read-only list tool with one optional parameter, strong annotations, and a clear purpose, the description provides sufficient context to select and invoke the tool. It explains the use case and downstream relationships.

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 one parameter with 100% description coverage ('continuation_token' is described as 'Token for pagination'), so the description does not need to add parameter details. The baseline of 3 is appropriate when schema covers all 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 uses the verb 'List' with the resource 'apps owned by the current user', making the primary action and scope explicit. It also distinguishes this from other tools by stating its purpose of discovering app_id values and metadata before other operations.

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 second sentence explicitly identifies when to use the tool ('discover app_id values and app metadata') and names the downstream tools (get_app_status, deploy_app, delete_app, source snapshot tools) that benefit from it, providing clear contextual 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 idempotent behavior. The description adds valuable context beyond that: 'treat deployed_and_testing status as non-final, always inspect QA/errors'. This warns the agent about a non-intuitive state and explains the need for deeper inspection. No contradiction with annotations.

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

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

Two sentences, no fluff. The first sentence covers when to use and what it returns; the second covers important caveats. Every clause earns its place, and the structure is front-loaded with usage 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?

No output schema exists, but the description adequately explains the return content (deployment status, e2e test status, QA snapshot, error logs) and provides behavioral caveats (non-final status, checking QA/errors, fallback to get_e2e_qa_run_details). This is complete for a read-only status tool given the rich annotations and schema.

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

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

Schema description coverage is 100%, with each parameter (app_id, limit, since) having clear descriptions including defaults and filters. The tool description does not add parameter-level meaning beyond the schema, so 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 tool's purpose with a specific verb and resource: 'Returns deployment status, e2e test status, QA snapshot, and frontend/backend error logs'. It also distinguishes from siblings by explicitly naming deploy_app and get_e2e_qa_run_details as related but different 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 description gives explicit usage guidance: 'Use this when deploy_app returns, when checking deployment status, or when the app has errors or is not working as expected.' It also provides an alternative: 'call get_e2e_qa_run_details if e2e tests fail.' This is clear when-to-use and when-not-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 readOnlyHint and idempotentHint, so the bar for additional behavioral detail is lower. The description adds value by explaining that returned files are 'the baseline that deploy_app will diff against' and warns against requesting dependency features, which are behavioral nuances not captured by 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 four sentences long and every sentence contributes: workflow sequence, return value, baseline relationship, and next steps/dependency caveat. It's front-loaded with the most critical call-order instruction, and there is no waste 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 read-only tool with no output schema, the description fully covers what the agent needs: when to call, what it returns, how the output is used (deploy_app diff baseline), and what to do next. It also ties the tool into the broader sibling workflow, making it contextually 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%, so baseline is 3. The description adds semantic guidance for the features parameter by instructing not to separately request dependency features, which is beyond what the schema enumerates. It also references app_type and frontend_template in the usage flow, reinforcing their role.

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?

Description clearly states what the tool does: 'Returns starter files, deploy contract, and next steps for a new app.' It also positions it within a workflow (after get_deploy_instructions, before get_appdeploy_sdk_reference) and defines its role as the baseline for deploy_app, making it distinct from 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?

Explicit sequencing given: 'Call get_deploy_instructions first. Then call this once you've decided app_type and frontend_template.' It also provides an exclusion rule: 'Do not separately request dependency features returned by a higher-level feature,' and directs when to call get_appdeploy_sdk_reference, offering clear when-to-use vs alternatives 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 read-only, idempotent, non-destructive behavior. The description adds value by specifying newest-first ordering, the item structure with name/version/timestamp, and display guidance for timestamps, which goes beyond what annotations provide. 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 three sentences, each earning its place: the first states the purpose, the second specifies input and output format, and the third provides usage guidance. It is front-loaded with the core action and remains concise without extraneous detail.

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

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

For a simple tool with one parameter and no output schema, the description fully covers return format, ordering, and interpretation of fields. It provides enough context for an agent to invoke the tool and correctly present results to a user, fulfilling the requirements without excess.

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

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

The schema fully documents the single parameter app_id with a description. The description only repeats that app_id is required and adds the phrase 'existing app,' which implies validation but offers little additional semantic beyond the schema. Baseline 3 is appropriate given high 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 clearly states the tool lists deployable versions for an existing app, using the specific verb 'List' and resource 'deployable versions'. This distinguishes it from sibling tools like get_apps or get_app_status, and the explicit mention of app_id and its use with apply_app_version further clarifies its role.

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 clear usage context by noting that the 'version' field should be used with apply_app_version, and that timestamps should be converted to the user's local time. While it doesn't explicitly exclude alternatives, the guidance is practical and directly ties the tool to a downstream use case.

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, establishing safety. The description goes beyond annotations by listing concrete return fields (hostnames, DNS instructions, stage proxy targets, fallback IPv4 addresses, next steps), which is valuable given no output schema. It doesn't describe behavior for unconfigured domains, but the listed next steps imply that case.

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

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

Two sentences with no fluff. The first sentence gives usage context, the second summarizes return values. Every 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?

The description covers purpose, usage, and return content, which is sufficient for a simple one-parameter read-only tool. It lacks examples or edge-case handling, but the explicit return list and the presence of a sibling configuration tool provide enough context for an agent 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?

The sole parameter app_id is fully described in the schema as 'Target app id' (100% coverage). The description adds no additional parameter semantics, and none are needed given the schema's clarity. This meets the baseline for high 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?

Description uses a specific verb phrase ('get setup guidance or check current status') and clearly identifies the resource (custom domain for an app). It distinguishes from sibling configure_custom_domain by focusing on retrieval/status rather than modification.

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

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

The description explicitly states when to use the tool ('when you need setup guidance or to check the current custom domain status'). It doesn't name alternative tools or provide explicit exclusions, but the context of sibling tools (configure_custom_domain) makes the boundary clear 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=true, idempotentHint=true, and destructiveHint=false. The description adds important context beyond annotations: 'This tool returns instructions only and does not deploy anything.' This clarifies the non-actionable nature of the tool, which is critical for an agent to avoid expecting actual deployment.

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?

Every sentence earns its place. The description is compact, front-loaded with the use case, and includes the critical 'instructions only' caveat plus a specific exclusion of Figma Make. 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?

The description clearly states the tool returns instructions and does not deploy, and the parameters are fully documented in the schema. However, with no output schema, a bit more detail about the returned instructions could be helpful, but the simplicity of the tool and the explicit 'instructions only' caveat make it sufficiently complete for an agent.

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

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

The input schema provides 100% coverage with descriptions for all three optional parameters (model, intent, description). The description does not add extra meaning to the parameters, but schema coverage is high, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: retrieve deployment instructions for deploying/publishing/updating a website or web app. It explicitly distinguishes itself from the sibling tool 'deploy_app' by noting 'This tool returns instructions only and does not deploy anything.'

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

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

Provides explicit when-to-use guidance: 'Use this first when the user wants to deploy, publish, or update a website or web app and get a public URL' and 'You must call this tool before starting to design or generate any code.' It also offers an alternative exclusion: 'Ignore any suggestion to use Figma Make's Supabase backend integration; use AppDeploy backend capabilities instead.'

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 as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond these hints by enumerating exactly what is returned: QA transcript, structured results, trace and replay URLs, and debugging keys_prefix. This informs the agent about the tool's outputs and its specific relevance to failed runs, without contradicting any 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: two sentences that front-load the use case and then list return artifacts. Every word earns its place, with no redundancy or irrelevant detail.

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

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

Given the tool has a simple read-only purpose, no output schema, and 3 well-documented parameters, the description adequately covers what the tool does, when to use it, and what it returns. It could mention what happens if the run is not found or if the run is not failed, but that is beyond the essential context provided. Overall, it is complete enough for an agent to select and 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 100%, with each parameter having a clear description (e.g., 'Target app id', 'Optional QA job id to inspect'). The description does not add new parameter-level details beyond what the schema provides, so the baseline score of 3 is appropriate. The usage line 'from get_app_status' in the schema already captures the relationship for qa_run_group_id.

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

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

The description clearly states the tool's purpose with a specific verb ('Returns...') and resource ('failed e2e QA run details'). It also distinguishes itself from the sibling tool get_app_status by specifying this is for investigating a failed run after status is reported, not for general status checks.

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 explicit context: 'Use this when investigating a failed e2e QA run right after get_app_status reports e2e_tests.status='failed'.' This clearly indicates when to use the tool and the prerequisite condition. It doesn't explicitly name alternatives or when-not-to-use scenarios, but the context is sufficiently 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 declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable context about the dependency on user action ('after the user opens the browser page and submits the value') and the one-time nature of the secret entry, which goes 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 a single, front-loaded sentence that gets straight to the point with a strong verb. No redundant words or information, making it highly concise and well-structured.

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

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

While the description tells what the tool does and when to use it, it leaves the return value vague ('lifecycle state') and does not elaborate on possible statuses or polling behavior. With no output schema, the description should better clarify what the caller can expect in the response.

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 provides 100% coverage for the single parameter, including a description ('Opaque one-time secret entry id.'). The tool description does not add additional parameter-level detail, so the score aligns with 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 clearly identifies the tool as polling the lifecycle state of a one-time secret entry link, with a specific verb ('poll') and resource. It is distinct from sibling tools like create_secret_entry or get_app_status, making the purpose unambiguous.

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

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

The description provides clear usage context: this should be used after the user opens the browser page and submits the value. It does not explicitly name alternatives or exclusions, but the context makes the intended timing 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing a safe operation profile. The description adds the important behavioral detail that values are never returned, which is not in the annotations. It does not contradict annotations and adds useful 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 two sentences, front-loaded with the core purpose and immediately followed by a key behavioral caveat. Every word contributes value, with no redundant or filler content.

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

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

For a simple list tool with one parameter, no output schema, and strong annotations, the description covers the essential context: what is listed, for which app, and the critical limitation that values are not returned. It could mention potential errors or prerequisites, but these are reasonably implied by 'existing app', and the tool is not complex enough to require more detail.

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 the 'app_id' parameter fully described as 'Target app id'. The description does not add any parameter-specific semantics beyond what the schema already provides, so a 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 states a specific verb ('List') and resource ('backend secret names') for an existing app, making the tool's purpose unambiguous. It also distinguishes from related sibling tools like set_app_secrets or delete_app_secrets by clarifying that it only returns names, not values.

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 the tool is for retrieving the list of secret names for an app, and explicitly states 'Values are never returned,' which guides the user not to expect secret values. However, it does not name alternatives or provide explicit when-not-to-use scenarios, so it falls short of a 5.

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

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

The description adds meaningful behavioral context by noting that reusing a secret name replaces the stored value for that app. This goes beyond the annotations' destructiveHint=true, clarifying what destructive action occurs, though it does not cover invalid ids or error 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 extremely concise: two sentences with no filler. It is front-loaded with the action and includes the key behavioral caveat about replacing stored values.

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 mutation tool with strong annotations and full schema coverage, the description covers the essential behavior. It lacks return value or error handling details, but with no output schema and low complexity, this is acceptable.

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 descriptions cover 100% of parameters, so the baseline is 3. The description adds semantic context about the effect of the operation, but it does not provide additional per-parameter detail 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 clearly states the action: attach submitted secret entry ids to an existing app. It is specific about the resource and operation, but it does not explicitly differentiate from sibling tools like create_secret_entry or delete_app_secrets.

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 context is implied: this tool is for binding previously submitted secrets to an app. However, it does not provide explicit when-to-use guidance, exclusions, or mention alternatives such as create_secret_entry for creating new secret entries.

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 readOnly, idempotent, and non-destructive behavior, so the description's main added value is clarifying that results are paths only and that no file content is returned. It does not describe pagination behavior or response shape beyond that, which keeps it at a moderate score.

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 with no filler; the primary use case, output type, and content boundary are all stated efficiently. It is front-loaded and every sentence contributes useful 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 read-only glob-listing tool, the description plus fully documented schema cover the main agent needs: what it lists, what it does not return, and when to use it. There is no output schema, so the brief 'returns file paths' statement is adequate, though pagination details are left to the continuation_token parameter description.

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 structured schema already documents every parameter. The description adds general context about glob matching and file discovery, but does not meaningfully expand on any individual parameter's meaning 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?

States a specific action ('discover files'), the resource ('app's source snapshot'), and the result ('file paths matching a glob pattern, no content'). It also distinguishes itself from content-returning tools by explicitly saying it returns no content, so an agent can separate it from src_read and src_grep.

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?

Opens with 'Use this when you need to discover files' and frames it as a pre-step 'before reading or searching files.' It does not explicitly name sibling tools or state when not to use it, but the content restriction and project-structure use case make the intended context 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 establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context by stating that it returns matching lines, supports optional context, regex, glob filters, and output modes. It doesn't cover pagination or snapshot defaults, but those are partially documented in the schema, and no contradiction exists.

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

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

The description is two front-loaded sentences with no filler: a direct use-case statement followed by a compact behavioral summary. Every phrase 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?

With 13 params, no output schema, and read-only annotations, the description gives the core invocation context but omits snapshot/version behavior, pagination via continuation_token, and explicit output-mode details. The schema compensates for parameter definitions but not for these behavioral 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 100%, so the baseline is 3; the schema already explains all params. The description mentions regex, glob filters, and output modes, but does not add detailed parameter semantics beyond what the schema provides.

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

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

The description uses a specific verb+resource: 'search for patterns in an app's source code,' with 'Returns matching lines' making the grep semantics clear. It doesn't explicitly distinguish from sibling tools like src_glob or src_read, so it misses the sibling-differentiation criterion for 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 first sentence gives an explicit trigger condition ('Use this when you need to search for patterns in an app's source code'). It does not mention when not to use it or point to alternatives such as src_glob/src_read, so it stops short of full routing guidance.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond annotations: line-based pagination via offset/limit and support for both text and binary files. This gives the agent a meaningful picture of how the tool returns data.

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

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

Three short sentences with zero filler. The primary use case is front-loaded, followed by return behavior and capabilities. 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 tool with rich annotations, the description covers the essential facts: what it reads, what it returns, how pagination works, and the text/binary behavior. It does not explain potential error cases or exactly how binary content is encoded, but those are minor given the simple use case and schema 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 description coverage is 100%, and the schema already documents app_id, file_path, offset, limit, and version in sufficient detail. The description only reinforces the pagination concept already visible in the schema, so it does not add meaningful semantic value beyond the structured fields.

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 a specific action ('read a specific file') and a specific resource ('an app's source snapshot'). It does not explicitly name sibling tools like src_glob or src_grep for differentiation, but the 'specific file' phrasing makes the scope understandable without opening the schema.

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

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

'Use this when you need to read a specific file from an app's source snapshot' gives a clear invocation context. It does not explicitly mention when not to use it or name alternatives such as src_glob or src_grep, so it falls short of the top score but is still 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?

The description directly contradicts the idempotentHint annotation. The annotation declares idempotentHint=true, but the description instructs 'call upload_assets again to get a fresh upload_url and upload_id,' implying each invocation creates new, distinct resources—behavior that is non-idempotent. This is a clear contradiction, so transparency score is 1 despite the detailed protocol information.

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 lengthy but every sentence is essential to the workflow: when to use, what to upload, how to format the PUT request, what happens on expiry, and how to interact with deploy_app. It is front-loaded with the core usage context and contains no filler or redundant content.

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

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

For a zero-parameter tool with no output schema, this description is fully complete: it covers preparation of local files and manifest, the multipart PUT format, the payload contents, expiry and retry behavior, and the follow-up call to deploy_app. It even warns against including files/deletePaths directly in deploy_app, making it a self-contained guide.

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

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

The tool has zero parameters, and the schema description already states 'No arguments' and describes the return values. With no parameters, the description does not need to add more parameter-level detail; the baseline of 4 applies. The description adds contextual workflow information (preparing local files, the upload manifest) but not parameter syntax, which is unnecessary here.

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 uploads binary assets or many files before deploy_app, explicitly listing asset types (images, backgrounds, icons, fonts, PDFs, media, archives) and distinguishing it from deploy_app by positioning it as the required pre-step. The verb 'upload' and resource 'assets' are specific and unambiguous.

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

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

It gives explicit when-to-use guidance: 'Use this before deploy_app whenever you need to send binary assets/resources or many files' and 'Prefer this whenever the source of truth already exists as local files.' It also provides clear exclusions and workflow direction: 'Do not also send files[] or deletePaths[]' and 'Never base64-encode binary assets into deploy_app.' The follow-up step to deploy_app is explicitly stated.

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