AppDeploy

by ai.appdeploy

Overview Discussions Admin

Server Details

AppDeploy turns app ideas described in AI chat into live full-stack web applications

Ownership verified

Status: Healthy
Uptime: 99.9% over 84 days
OAuth: Works in Glama
Last Tested: 2026-11-09 00:29
Transport: Streamable HTTP · MCP 2025-11-25
URL
ChatGPT: –
Claude: AppDeploy

TDQS

A3.6/5.0

Scored 2026-11-01 14:50 across 26 tools

Disambiguation4/5

Most tools map cleanly to a single resource+action (secrets, domains, resources, source, apps), and the descriptions explicitly separate look-alikes such as upload_resources (collect binaries) vs set_app_resources (bind to app) and deploy_app (publish source) vs apply_app_version (restore snapshot). The main soft spots are the four near-parallel '*_instructions' tools and the deploy/update/apply family, where an agent must read the prose to pick correctly rather than inferring from the name alone.

Naming Consistency3/5

The dominant pattern is verb_noun snake_case (deploy_app, delete_app, get_apps, set_app_secrets, verify_custom_domain), but it is broken by the resource-prefixed read trio src_glob/src_grep/src_read and by the oddly namespaced appdeploy_who_am_i. The conventions are still readable and mostly decodable, but there is no single predictable scheme an agent can rely on when guessing a new tool name.

Tool Count3/5

At 26 tools the surface is heavy for a deployment server, and a meaningful chunk is documentation scaffolding: get_deploy_instructions, get_secret_entry_instructions, get_resource_upload_instructions, get_custom_domain_instructions and get_appdeploy_sdk_reference could plausibly be consolidated. The remaining tools are each tied to a real sub-domain (apps, versions, secrets, uploads, DNS, source search), so the count is broad rather than padded.

Completeness4/5

The lifecycle is largely covered: deploy/update/delete apps, list and restore versions, check status and errors, full secret create/bind/list/delete flow, domain add/verify/delete, resource upload/bind/status, plus source glob/grep/read for debugging. Minor gaps remain — no explicit stop/restart or app metadata update, no way to cancel or delete an in-flight upload/secret entry, and no way to remove a stored version — but agents can work around these.

Available Tools

26 tools

add_custom_domainAdd a custom domainAInspect

Call this tool to connect a domain to an app. Pass app_id, domain and dns_mode (subdomain_cname or apex_address). Call get_custom_domain_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	Yes	Target app id
`domain`	Yes	Hostname to connect to this app
`dns_mode`	Yes	DNS routing mode for this hostname
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. Beyond that the description only adds that a DNS workflow is involved via the instructions tool; it doesn't say what actually happens after the call (DNS record creation, propagation, when verification becomes possible) or whether re-calling is safe. It contributes useful direction but little behavioral depth.

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

Conciseness4/5

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

Three short sentences, front-loaded with the action, then parameters, then the hand-off to the instructions tool. The trailing "MCP version 2.12." fragment is terse but useful for populating mcp_version. No wasted prose.

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

Completeness4/5

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

For a 4-parameter, fully documented, annotated tool with no output schema, the description covers what an agent needs to invoke it and points to the workflow tool for anything further. The main remaining gap is that the post-call path (verify_custom_domain) is not surfaced here, deferred entirely to get_custom_domain_instructions.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters are already documented, including the enum values and the mcp_version pattern. The description restates the required parameters and the two dns_mode values, which duplicates rather than extends the schema. The one additive detail is pinning MCP version 2.12, already present in the mcp_version schema description, so the baseline 3 is appropriate.

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

Purpose4/5

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

States a specific verb and resource: "connect a domain to an app," which is clearly an additive operation distinct from siblings named delete_custom_domain and verify_custom_domain. The required parameters are named, so the agent understands the shape of the call. It stops short of explicitly contrasting itself with those siblings, but the name plus verb make the intent unambiguous.

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

Usage Guidelines4/5

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

Explicitly routes the agent: "Call get_custom_domain_instructions for usage and workflow," which tells the caller that prerequisite/workflow knowledge lives in a sibling tool. It gives clear triggering context (connecting a domain to an app) but no when-not-to-use conditions and doesn't mention verify_custom_domain as a follow-up step, leaving that to the instructions tool.

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

appdeploy_who_am_iShow connected AppDeploy accountA

Read-onlyIdempotent

Inspect

Use this tool to inspect the signed-in account, apps, subscription and credit balances. Set profile_only:true for identity details only; omit it for billing and credits. Use limit and continuation_token to page through apps. MCP version 2.12.

Name	Required	Description
`limit`	No	Maximum apps per page (default 20, maximum 100)
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`profile_only`	No	Return only the connected user profile, skipping apps, subscription, and credits. Defaults to false.
`continuation_token`	No	Apps pagination token from the previous account overview

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: the exact data sections returned (profile, apps, subscription, credits), that pagination applies only to apps, and that the token comes from a prior call. It stops short of describing response shape or whether a token expires.

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

Conciseness5/5

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

Three short sentences, front-loaded with the tool's purpose before the parameter branches. The trailing 'MCP version 2.12' line is not filler — it supplies the literal value required by the mcp_version parameter's pattern and description.

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

Completeness4/5

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does: profile, apps, subscription, and credits, split by profile_only. Combined with full schema coverage and complete annotations, the only gap is pagination specifics (token lifetime, whether the app list is exhaustive).

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including defaults, max limit of 100, and the continuation token source. The description restates profile_only and pagination behavior rather than adding new semantics, which lands at the baseline for a fully-documented schema.

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

Purpose4/5

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

The description names a specific verb and resource: inspecting the signed-in account plus apps, subscription, and credit balances, so the agent knows exactly what data this tool surfaces. It does not, however, explicitly distinguish itself from the sibling get_apps, which also returns app data via pagination, leaving a small ambiguity about which to pick for a pure app listing.

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

Usage Guidelines4/5

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

Clear conditional guidance is given for the main branch: set profile_only:true for identity only, omit it to include billing and credits, and use limit/continuation_token to page apps. What's missing is any exclusion or routing statement against get_apps or get_app_status, so the when-not guidance is incomplete.

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

apply_app_versionApply a former app versionA

DestructiveIdempotent

Inspect

Call this tool to restore an app's stored version, replacing its running deployment. Pass app_id and the internal version returned by get_app_versions. MCP version 2.12.

Name	Required	Description
`app_id`	Yes	Target app id
`version`	Yes	Version id to apply
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already disclose that this is a destructive, idempotent, open-world mutation. The description adds important behavioral context by saying it replaces the running deployment, which tells the agent what effect to expect beyond the structured hints.

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

Conciseness5/5

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

It is front-loaded with the action and effect, then gives the required inputs and version constraint. There is no wasted text, and the MCP version note is relevant to the mcp_version parameter.

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

Completeness4/5

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

For a three-parameter destructive mutation with full schema descriptions and annotations, the description provides enough context to invoke it correctly. It could optionally mention the result of applying a version, but the absence of an output schema makes that a minor gap.

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

Parameters4/5

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 meaningful guidance for the version parameter by saying it is the internal version returned by get_app_versions, going beyond the schema's short 'Version id to apply' description.

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

Purpose4/5

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

The description states a specific verb and resource: restore an app's stored version by replacing its running deployment. It clearly separates this from simply deploying an app, though it does not explicitly name deploy_app as the alternative.

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

Usage Guidelines4/5

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

It gives a clear usage context and prerequisite: call this to restore a stored version, using the internal version returned by get_app_versions. It does not spell out when not to use it or compare it directly with deploy_app.

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

create_secret_entryConfigure app securelyAInspect

Use this tool to create a secure form for app configuration, such as backend API keys. Pass parameter names only in secret_names; optional app_id scopes the entries. Users enter values only in the form. Creating entries does not bind them to an app. Returns a widget and an external intake URL; offer both so the user can choose, and use the URL when the widget is unavailable. Call get_secret_entry_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	No	Optional existing app id. Omit this when preparing secrets for a brand-new app before deploy_app.
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`secret_names`	Yes	All secret names needed for this request, together in one array and one call. Use a one-element array for one secret. Never supply values or split names across separate calls.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations declare readOnlyHint=false but destructiveHint=false, and the description corroborates this by explaining that the tool creates entries without binding them to an app and that users supply values only via the form. It goes well beyond the annotations with the critical safety detail that values must never be passed as parameters, plus the return shape (widget and external intake URL). It omits idempotency behavior (idempotentHint=false) and what a repeat call produces.

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

Conciseness4/5

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

Purpose and the key constraint (names only, no values) are front-loaded, and the sentences are dense with operational instructions. The trailing "MCP version 2.12" is redundant with the schema's mcp_version description, a minor waste.

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

Completeness4/5

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

With no output schema, the description correctly compensates by describing the return values (a widget and an external intake URL) and how to present them. Combined with full schema coverage, an agent has enough to call it correctly; only repeat-call/idempotency behavior is unaddressed.

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

Parameters3/5

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

Schema description coverage is 100%, so both app_id and secret_names are already fully documented, including the new-app / pre-deploy_app guidance. The description reinforces that only names go in secret_names and that app_id scopes entries, but adds no syntax or format detail beyond the schema. Baseline 3 applies when the schema carries the load.

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

Purpose4/5

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

States a specific verb and resource: "create a secure form for app configuration" fed by secret names. It also distinguishes itself implicitly from the write-oriented siblings by noting "Creating entries does not bind them to an app" and "Users enter values only in the form," which separates it from set_app_secrets, though no sibling is named explicitly.

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

Usage Guidelines4/5

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

Provides concrete usage directives: pass names only, offer both the widget and the external URL, and "use the URL when the widget is unavailable." It routes deeper workflow questions to get_secret_entry_instructions instead of answering them inline, which is a reasonable hand-off but leaves the workflow itself unspecified here.

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

delete_appDelete appA

Destructive

Inspect

Call this tool only when the user requests permanent app deletion. Pass app_id to delete the app and its associated data. MCP version 2.12.

Name	Required	Description	Default
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A4/5.0

Behavior4/5

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 known. The description still adds real value by disclosing that the deletion is permanent and cascades to the app's associated data, which is the key behavioral consequence an agent needs. It omits any mention of required permissions or irreversibility recovery.

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

Conciseness4/5

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

Three short sentences, with the gating condition first, then the action, then the version note. The final fragment 'MCP version 2.12.' is terse but directly supports the required mcp_version parameter, so it earns its place.

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

Completeness5/5

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

For a two-parameter destructive tool with fully covered schema and complete destructive/idempotency annotations, the description covers when to call it, what is removed (app plus associated data), and the permanent nature of the operation. With no output schema expected, nothing an agent needs in order to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and both parameters are documented in the schema itself, including the mcp_version pattern and its instruction to use "2.12". The description's 'Pass app_id' and 'MCP version 2.12' merely restate what the schema already says, adding no format or edge-case detail beyond it.

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

Purpose4/5

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

States a specific verb and resource: delete an app, and clarifies that associated data goes with it, which separates it from the sibling delete_app_secrets / delete_custom_domain tools in effect if not by name. It never explicitly names those siblings, so an agent must infer the boundary from the 'associated data' phrasing.

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

Usage Guidelines4/5

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

'Call this tool only when the user requests permanent app deletion' is a genuine gating condition that is front-loaded, giving clear when-to-use context. It stops short of naming explicit alternatives (delete_app_secrets, apply_app_version) or stating when-not-to-use it, so no exclusions are covered.

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

delete_app_secretsDelete app secretsA

DestructiveIdempotent

Inspect

Call this tool when the user requests secret removal. Pass app_id and secret_names to delete those secrets from the app. Call get_secret_entry_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`secret_names`	Yes	Secret names to delete from the app. Missing names are ignored.

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is covered externally. The description adds little beyond that – it never states that deletions are irreversible, what happens to secrets currently referenced by a deployed version, or whether a confirmation step is expected. Adequate, but thin for a destructive mutation.

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

Conciseness4/5

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

Three compact sentences, front-loaded with the trigger condition, and the workflow pointer follows logically. The trailing 'MCP version 2.12.' is a fragment, but it does help the agent populate the required mcp_version parameter.

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

Completeness3/5

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

For a destructive, irreversible mutation with no output schema, the description covers trigger, key inputs, and a workflow pointer, and annotations carry the safety hints. It omits consequences of deletion and any preconditions, which an agent would want before invoking a destructive tool.

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

Parameters3/5

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

Schema description coverage is 100%, including the note that missing names are ignored and the uppercase env-style pattern. The description only restates 'pass app_id and secret_names', adding no format or edge-case 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.

Purpose4/5

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

States a specific verb+resource (remove secrets from an app) and names the two required inputs, so the action is unambiguous. It does not explicitly contrast with siblings like set_app_secrets or create_secret_entry, but the 'delete' wording is distinct enough to route correctly.

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

Usage Guidelines4/5

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

Gives a clear trigger ('when the user requests secret removal') and points to get_secret_entry_instructions for usage and workflow details. No explicit when-not or prerequisite guidance (e.g., confirm before deleting), so it stops short of a 5.

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

delete_custom_domainDelete a custom domainA

Destructive

Inspect

Call this tool with app_id and domain when the user requests removal of that custom-domain connection. Call get_custom_domain_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	Yes	Target app id
`domain`	Yes	Hostname mapping to remove from this app
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A4/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is provided structurally. The description adds the custom-domain connection scope and version requirement but does not add details about irreversibility, permissions, or side effects 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.

Conciseness5/5

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

The description is three short sentences with no waste. The usage condition is front-loaded, the workflow pointer follows, and the version note supports the required mcp_version parameter.

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

Completeness4/5

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

For a destructive tool with rich annotations, full schema coverage, and sibling instructions, the description is largely complete: it identifies the action, parameters, and workflow pointer. A minor gap is that it does not explicitly warn about the destructive nature or confirmation requirements, though annotations already flag that context.

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

Parameters3/5

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

Schema description coverage is 100%, so app_id, domain, and mcp_version are already documented. The description mentions app_id, domain, and MCP version 2.12, but adds no semantic detail beyond what the schema already provides.

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

Purpose5/5

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

The description states a specific removal action for a specific resource: 'removal of that custom-domain connection' using app_id and domain. This clearly distinguishes it from add_custom_domain and verify_custom_domain without requiring schema inspection.

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

Usage Guidelines4/5

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

It gives a clear usage condition: call this when the user requests removal of the custom-domain connection. It also routes the agent to get_custom_domain_instructions for usage and workflow, though it does not explicitly state when not to use this tool or name alternative deletion paths.

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

deploy_appDeploy appA

Destructive

Inspect

Call this tool to publish or update an app at a public URL. Strictly follow get_deploy_instructions preflight, hard rules and workflow. Pass app_name, app_type, model and intent. New apps also need app_id:null, description, frontend_template and text files; optionally bind resource_upload_ids and secret_entry_ids. Updates/retries use app_id with files/diffs and deletePaths, or omit edits to retry saved source. Updates can overwrite source files and replace the running deployment. Optional: initiator, type. MCP version 2.12.

Name	Required	Description
`type`	No	Optional deploy change type, for example 'fix', 'feature', 'refactor', 'performance', 'test', 'docs', 'chore', or 'style'.
`files`	No	Text source files and diffs. Omit for an existing-app redeploy of the saved source snapshot.
`model`	No	Coding model used; use 'chat' if unknown.
`app_id`	No	MANDATORY: existing app id to update, or null for new app
`intent`	No	Short summary of the requested app change.
`app_name`	Yes	short display name
`app_type`	Yes	app architecture: frontend-only or frontend+backend
`initiator`	No	Request initiator, e.g. user or agent.
`deletePaths`	No	Paths to delete. ONLY for updates (app_id required). Cannot delete package.json or framework entry points.
`description`	No	short description of what the app does
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`secret_entry_ids`	No	Submitted secret entry IDs for a new app. Existing apps use set_app_secrets.
`frontend_template`	No	REQUIRED when app_id is null. One of: 'html-static' (simple sites), 'react-vite' (SPAs, games), 'nextjs-static' (multi-page). Template files auto-included.
`resource_upload_ids`	No	Completed upload IDs to bind when creating a new app. Existing apps use set_app_resources.

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds needed context beyond them: updates 'can overwrite source files and replace the running deployment,' and an update with no edits silently redeploys the saved snapshot. That is real consequence disclosure. It omits permissions/auth and failure behavior, so 4 rather than 5.

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

Conciseness4/5

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

Front-loaded with the action and the preflight obligation, then the create/update parameter shapes; no filler sentences. It is dense to the point of being a run-on, and the phrase 'hard rules and workflow' is vague without saying what those rules are.

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

Completeness4/5

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

For a 14-parameter mutation tool with no output schema, the description covers the critical decisions: create vs. update, edits vs. retry, file/diff/delete semantics, and the version handshake. It does not tell the agent what a successful deploy returns (URL, status), but no output schema exists so that gap is more forgivable here.

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

Parameters4/5

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

With 100% schema coverage the baseline is 3, but the description adds conditional meaning the schema doesn't encode on its own: which parameters belong to the create path (app_id:null, description, frontend_template, secret_entry_ids, resource_upload_ids) versus the update path (app_id, files/diffs, deletePaths). It also states the required MCP version value ('2.12'), tying the mcp_version parameter to a concrete literal.

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

Purpose5/5

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

States a specific verb and resource — 'publish or update an app at a public URL' — and immediately splits the two modes (new app vs. update/retry) so an agent knows which shape applies. It names the required preflight sibling get_deploy_instructions, which distinguishes it from the other app tools.

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

Usage Guidelines4/5

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

Gives clear when-to-use guidance: new apps need app_id:null plus description/frontend_template/files; updates/retries use app_id with diffs/deletePaths, or omit edits to retry saved source. It mandates the get_deploy_instructions preflight, which is an explicit prerequisite. It lacks an explicit 'do not use for deletion, use delete_app' exclusion, so not a 5.

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

get_appdeploy_sdk_referenceGet AppDeploy SDK referenceA

Read-onlyIdempotent

Inspect

Use this tool before coding against @appdeploy/client or @appdeploy/sdk. Pass one feature: api, realtime, auth, notifications, invites, database, storage, secrets, ai.generate, ai.extract, ai.ocr, ai.classify, ai.scrape, ai.run, ai.image, cron. Returns types, rules, examples and dependencies. MCP version 2.12.

Name	Required	Description	Default
`feature`	Yes	One SDK feature per call; dependency references are included automatically.
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare it as a read-only, idempotent, non-destructive, closed-world lookup, so the burden is low. The description adds real value by disclosing the return contents (types, rules, examples, dependencies) and that dependency references come automatically, plus the version pinning expectation.

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

Conciseness4/5

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

The use-before-coding instruction is front-loaded and the version note is short. The long enumeration of feature values repeats the schema enum and adds bulk without new information, keeping it below a 5.

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

Completeness4/5

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

With no output schema, the description correctly compensates by summarizing what is returned (types, rules, examples, dependencies). It also notes the auto-included dependency references. Only the exact response shape/scoping remains unspecified, which is acceptable for a reference lookup.

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

Parameters3/5

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

Schema coverage is 100% and the enum is already enumerated in the schema, so the description's list of feature values largely duplicates structured data. It adds only the 'one feature per call' constraint, which the schema description already conveys – baseline 3 is right.

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

Purpose5/5

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

States a specific verb and resource ('get...SDK reference') and scopes it to coding against @appdeploy/client or @appdeploy/sdk. It is clearly distinguishable from the deployment/secret/domain CRUD siblings, which is the only reference-lookup tool in the set.

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

Usage Guidelines4/5

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

'Use this tool before coding against...' gives an explicit trigger condition, and 'Pass one feature' sets the invocation pattern. It doesn't name an alternative or state when-not to use it, but no sibling meaningfully overlaps, so the guidance is clear if not exhaustive.

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

get_appsList user's appsA

Read-onlyIdempotent

Inspect

Use this tool to list the user's apps. Pass continuation_token to fetch the next page. MCP version 2.12.

Name	Required	Description	Default
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`continuation_token`	No	Token for pagination

TDQS

A3.5/5.0

Behavior3/5

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

The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description does not need to restate that. It adds pagination behavior via continuation_token, but does not describe return shape, default page size, or other behavioral limits.

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

Conciseness4/5

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

The description is short and front-loads the primary purpose, with pagination guidance following naturally. The final sentence about MCP version 2.12 is somewhat redundant with the schema's mcp_version description but remains concise overall.

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

Completeness4/5

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 no required parameters, rich annotations, and full schema coverage, the description is largely sufficient. It could say more about what an app record contains, but with no output schema that omission is relatively minor.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces continuation_token for pagination but adds no syntax or semantics beyond what the schema already provides; baseline 3 is appropriate.

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

Purpose4/5

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

The description gives a clear verb and resource ('list the user's apps'), which is more specific than the title alone. It does not differentiate from related siblings such as get_app_versions or get_app_status, 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.

Usage Guidelines3/5

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

It provides pagination guidance by telling the caller to pass continuation_token for the next page, which is useful contextual usage. However, it gives no explicit when-to-use/when-not-to-use guidance or comparison against sibling tools.

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

get_app_statusGet app statusB

Read-onlyIdempotent

Inspect

Use this tool with app_id to check deployment state, errors and logs. Optional since (epoch milliseconds) and limit filter errors; resources_only:true returns the resource inventory. MCP version 2.12.

Name	Required	Description
`limit`	No	Optional shared cap for returned logs across frontend and backend combined. Defaults to 50 when omitted.
`since`	No	Optional timestamp in epoch milliseconds to filter errors. When provided, returns only errors since that timestamp.
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`resources_only`	No	Read the app's resource slots and uploaded paths without polling QA or starting a deployment.

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds one real behavioral detail (resources_only returns inventory) but omits the notable trait the schema references, namely that a normal call polls QA and may start a deployment. That omission matters more than the safety restatement.

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

Conciseness4/5

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

Three short sentences, front-loaded with the core action, and no filler. The trailing "MCP version 2.12" is terse and functional, though it duplicates the schema's mcp_version description rather than adding anything.

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

Completeness3/5

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

For a 5-parameter read tool with no output schema, the description covers the main parameters but never characterizes the return shape beyond "deployment state, errors and logs", and leaves the default (non-resources_only) side effects undisclosed. Adequate to make the call, thin for predicting what comes back.

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

Parameters3/5

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 does gloss since as epoch milliseconds and name the resources_only effect, but its claim that "since and limit filter errors" conflicts slightly with the schema, where limit is a shared cap across frontend and backend logs. That introduces mild noise rather than added meaning.

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

Purpose4/5

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

The description opens with a specific verb+resource combo ("check deployment state, errors and logs") scoped to app_id, which is enough to separate it from siblings like get_apps, get_app_versions, and get_upload_status. It stops short of explicitly naming a sibling it is not, so a 4 rather than a 5.

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

Usage Guidelines3/5

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

"Use this tool with app_id to check deployment state" implies the calling context, and the resources_only clause hints at a distinct mode of use. But there is no explicit when-to-use versus when-to-use-something-else guidance, and no mention of when to prefer get_app_versions or get_upload_status instead. Usage is inferable, not stated.

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

get_app_versionsGet available app versionsA

Read-onlyIdempotent

Inspect

Use this tool with app_id to list stored versions before choosing a version to restore. MCP version 2.12.

Name	Required	Description	Default
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the sequencing cue (list before restoring) but says nothing about result ordering, pagination, or volume of versions returned.

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

Conciseness4/5

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

Two short sentences with no filler, and the action plus the workflow rationale are front-loaded. The trailing 'MCP version 2.12.' is terse but serves the required mcp_version parameter.

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

Completeness4/5

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

For a simple read-only two-parameter listing tool with full schema coverage and rich annotations, the definition supplies everything needed to select and invoke it. The only gap is that no output schema exists and the description does not characterize the returned version entries.

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

Parameters3/5

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

Schema coverage is 100% and both parameters are documented in-schema, so the baseline is 3. The description reinforces the app_id target and hints at the mcp_version value ('MCP version 2.12'), but adds no syntax or format detail beyond the schema.

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

Purpose4/5

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

The description states a specific verb and resource ('list stored versions' for an app), and the phrase 'before choosing a version to restore' implicitly distinguishes it from the mutating sibling apply_app_version. It is clear without explicitly naming a sibling tool.

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

Usage Guidelines4/5

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

It gives clear usage context: call it with app_id to enumerate versions before selecting one to restore, which maps directly onto the restore workflow. It stops short of explicitly naming apply_app_version as the alternative or stating exclusions, so it lands just below the top score.

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

get_custom_domain_instructionsGet custom domain instructionsA

Read-onlyIdempotent

Inspect

Use this tool with app_id to check custom-domain status or get DNS and verification instructions before connecting a domain. MCP version 2.12.

Name	Required	Description	Default
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.8/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds workflow context (use before connecting a domain) but says nothing about what the status output contains or how it behaves when no domain is configured.

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

Conciseness5/5

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

Two short sentences, front-loaded with the action and the workflow context, with no filler. The trailing version note is necessary because the schema requires that exact value.

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

Completeness4/5

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

A simple two-parameter read-only tool with full schema coverage and rich annotations; no output schema exists, but the description conveys enough about what is returned (status, DNS and verification instructions) 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.

Parameters3/5

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

Schema description coverage is 100%, so both app_id and mcp_version are already documented in the schema. The description only restates that app_id is the input and repeats the version string, adding no semantics beyond the schema.

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

Purpose4/5

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

States a specific verb+resource: check custom-domain status or retrieve DNS/verification instructions for an app_id. It implicitly differentiates from add_custom_domain and verify_custom_domain via the 'before connecting a domain' framing, though it never names those siblings explicitly.

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

Usage Guidelines4/5

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

Gives clear usage context ('check custom-domain status or get DNS and verification instructions before connecting a domain'), which implies the read-first workflow preceding add_custom_domain/verify_custom_domain. It does not explicitly state exclusions or name the alternative tools.

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

get_deploy_instructionsGet deploy instructionsA

Read-onlyIdempotent

Inspect

Use this tool when the user wants AppDeploy to build or deploy an app. Returns workflow, coding guidance and starter files. Choose app_type (frontend-only or frontend+backend) and frontend_template (html-static, react-vite or nextjs-static); defaults are frontend+backend and react-vite. Set realtime for WebSockets/live updates; optionally provide model, intent and description. MCP version 2.12.

Name	Required	Description
`model`	No	Optional model name if known, for example 'gpt-5.5'. Omit or use null when unknown.
`intent`	No	Optional intent of this deployment. User-initiated examples: 'initial app deploy', 'bugfix - ui is too noisy'. Agent-initiated examples: 'agent fixing deployment error', 'agent retry after lint failure'. If no specific intent was given use 'app deploy'.
`app_type`	No	Optional app architecture. Defaults to 'frontend+backend' when omitted, including when frontend_template is provided.
`realtime`	No	Set true only when the app needs live cross-client updates, WebSocket subscriptions, or realtime collaborative state. Leave false or null for normal backend APIs, database, auth, AI, storage, secrets, notifications, invites, or cron.
`description`	No	Optional one-line summary of the user prompt or agent task.
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`frontend_template`	No	Optional frontend framework. Defaults to 'react-vite' when omitted, including when app_type is provided.

TDQS

A3.7/5.0

Behavior4/5

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 useful context beyond that: it lists the return contents (workflow, guidance, starter files) and documents default values, which helps the agent predict behavior. It doesn't discuss auth or rate limits, but against rich annotations this is solid.

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

Conciseness4/5

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

The description is a single dense paragraph that front-loads the primary usage trigger and return value before covering parameters and version. It's efficient, though the parameter enumeration makes it slightly list-like rather than maximally tight.

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

Completeness4/5

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

With no output schema, the description carries return-value burden and does so by summarizing the returned workflow, guidance, and starter files. All parameters are optional and the defaults are stated, so an agent has enough to call it correctly; only the relationship to the actual deploy tool is left implicit.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all seven parameters, establishing a baseline of 3. The description reiterates the key defaults for app_type and frontend_template and explains when to set realtime, but adds no syntax or format detail beyond what the schema provides.

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

Purpose4/5

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

The description states a specific verb and resource ('Get deploy instructions'), plus what it returns—workflow, coding guidance, and starter files. It's clear this is an instruction-fetching tool rather than the actual deploy operation, though the opening phrase 'when the user wants AppDeploy to build or deploy an app' slightly overlaps with the separate deploy_app sibling, keeping 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.

Usage Guidelines3/5

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

It gives a clear trigger ('when the user wants AppDeploy to build or deploy an app') and explains parameter choices, but it never mentions deploy_app or any other sibling as an alternative, nor when NOT to use it. The usage context is implied rather than explicitly differentiated from the deploy action tool.

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

get_resource_upload_instructionsGet resource upload instructionsA

Read-onlyIdempotent

Inspect

Use this tool before preparing binary resource uploads to learn the upload and binding workflow. No parameters required. MCP version 2.12.

Name	Required	Description	Default
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so behavior is well covered structurally; the description's only added behavior is that this is a preparatory step. The line "No parameters required" is a mild risk since the schema offers an mcp_version parameter it asks callers to set, and the description never says what the response looks like (instructions text, steps, version-specific notes).

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

Conciseness4/5

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

Three short sentences, front-loaded with the usage trigger, with no filler. The trailing version stamp is slightly orphaned but does carry meaning.

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

Completeness3/5

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

With no output schema, the description should convey what the caller receives and how it feeds the next step; "upload and binding workflow" is the only hint. Adequate to call the tool, but thin for a versioned, workflow-shaping instruction endpoint that sits alongside set_app_resources and upload_resources.

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

Parameters3/5

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

Schema coverage is 100% and the single parameter carries its own detailed description tying it to "2.12", so baseline 3 applies. The description's "MCP version 2.12." echoes the schema rather than clarifying when to pass mcp_version versus omit it, which the "No parameters required" phrasing arguably muddies.

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

Purpose4/5

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

States a specific verb and resource: it returns the upload and binding workflow instructions for binary resources. An agent can distinguish it from upload_resources and get_upload_status, though the description never names those siblings to sharpen the contrast.

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

Usage Guidelines4/5

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

"Use this tool before preparing binary resource uploads" gives an explicit trigger point in the workflow. It offers no exclusions or named alternatives (e.g., when to skip straight to upload_resources), 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.

get_secret_entry_instructionsGet secret entry instructionsA

Read-onlyIdempotent

Inspect

Use this tool to read instructions for AppDeploy's secure secret-entry workflow, including submission, status checks and app binding. No parameters required. Returns documentation only; does not request or accept secret values. MCP version 2.12.

Name	Required	Description	Default
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior. The description contributes new context: it 'returns documentation only' and never asks for or accepts secret values, which materially reassures an agent handling credential topics. Return format beyond 'documentation' is not detailed, but no output schema exists and the tool is trivial.

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

Conciseness5/5

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

Three short sentences, purpose stated first, then the parameter note and the safety exclusion, then the version tag. No filler; every sentence carries information an agent needs.

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

Completeness5/5

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

For a zero-required-param, read-only documentation tool with full schema coverage and no output schema, the description covers what it does, what it returns, what it does not do, and the version binding. Nothing needed to invoke it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and the single optional mcp_version parameter is fully documented in the schema, including the exact required value. The description's 'No parameters required' and 'MCP version 2.12' corroborate the schema but add no semantics beyond it, so baseline 3 applies.

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

Purpose4/5

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

States a specific verb ('read instructions') and a scoped resource ('AppDeploy's secure secret-entry workflow'), enumerating the covered topics: submission, status checks, app binding. An agent can distinguish it from create_secret_entry or get_secret_entry_status because it explicitly says it returns instructions rather than performing those actions. It does not name siblings, so a 4 rather than a 5.

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

Usage Guidelines4/5

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

'Use this tool to read instructions...' plus the exclusion 'does not request or accept secret values' clearly marks the boundary against the actual submission tools. No explicit when-not or named alternative is given, which keeps it out of 5 territory, but an agent will not misfire with it.

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

get_secret_entry_statusGet secret entry statusA

Read-onlyIdempotent

Inspect

Use this tool with secret_entry_id to check whether a secret has been submitted, consumed or expired. Secret values are never returned. Call get_secret_entry_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description	Default
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`secret_entry_id`	Yes	Opaque one-time secret entry id.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral information the annotations cannot convey: that secret values are never returned, and which status values to expect. No mention of error behavior for an unknown or already-expired id.

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

Conciseness4/5

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

Three short sentences, front-loaded with the action and the non-disclosure guarantee. The trailing 'MCP version 2.12.' is a fragment but is functional, reinforcing what belongs in the mcp_version parameter.

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

Completeness4/5

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

There is no output schema, so the description must indicate what comes back, and it does by naming the three possible statuses plus the guarantee of no secret values. For a simple two-parameter read tool this is nearly complete; only failure semantics for a bad entry id are unaddressed.

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

Parameters3/5

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

Schema description coverage is 100%; both secret_entry_id ('Opaque one-time secret entry id') and mcp_version are documented in the schema. The description only restates that secret_entry_id is the driving parameter and adds a version note, so it does not meaningfully exceed the schema's own documentation.

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

Purpose5/5

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

States a specific verb and resource ('check whether a secret has been submitted, consumed or expired') and enumerates the exact states returned. An agent can immediately distinguish this read-only status check from write-oriented siblings like create_secret_entry or set_app_secrets.

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

Usage Guidelines4/5

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

Gives clear invocation context ('use with secret_entry_id to check status') and routes the agent to get_secret_entry_instructions for the surrounding workflow. It does not state when NOT to use this tool or name a status alternative, so it falls short of full when/when-not coverage.

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

get_upload_statusget upload statusA

Read-onlyIdempotent

Inspect

Use this tool with upload_id to check upload progress, validation errors, uploaded paths, deadlines and binding status. Call get_resource_upload_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description	Default
`upload_id`	Yes
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.9/5.0

Behavior4/5

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 substantive payload — progress, validation errors, uploaded paths, deadlines, binding status — which is exactly what an agent needs to know this is a polling/status read. It stops short of saying whether results become stale or when polling is unnecessary.

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

Conciseness4/5

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

Three short sentences, front-loaded with the core behavior and the sibling redirect immediately after. The trailing 'MCP version 2.12.' is boilerplate but is needed to justify the mcp_version pattern constraint, so it earns its place.

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

Completeness4/5

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

With no output schema, the description compensates by enumerating the returned fields, which is the key completeness requirement here. The main remaining gap is the origin/validity of upload_id, which neither the description nor the schema covers.

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

Parameters3/5

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

Schema coverage is 50%: mcp_version is fully documented in the schema, but upload_id has no schema description. The description only says to use it 'with upload_id' and does not state where the id comes from (presumably upload_resources) or what happens on an unknown id. Baseline 3 applies since the schema carries most weight.

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

Purpose4/5

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

Names a specific verb and resource ('check upload progress, validation errors, uploaded paths, deadlines and binding status'), which tells an agent exactly what it will learn. It also distinguishes itself from get_resource_upload_instructions by pointing there for workflow instead of duplicating it, though the phrasing 'use this tool with upload_id' is slightly procedural rather than descriptive.

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

Usage Guidelines4/5

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

Explicitly routes the agent to get_resource_upload_instructions for usage and workflow, giving a clear boundary between the two tools. It does not state when the tool should not be called (e.g. before an upload exists or with an expired upload_id).

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

list_app_secretsList app secret namesA

Read-onlyIdempotent

Inspect

Use this tool with app_id to list backend secret names and metadata without revealing values. Call get_secret_entry_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description	Default
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.9/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description still adds non-obvious behavior beyond them: values are never revealed, only names and metadata, and the version handshake requirement is restated. Minor gaps remain (no mention of pagination or result size).

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

Conciseness4/5

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

Three short sentences, front-loaded with the action and followed by the workflow pointer and version note. Little waste, though the trailing 'MCP version 2.12' is a mechanical detail that could be left entirely to the schema.

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

Completeness4/5

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

No output schema exists, and the description compensates by characterizing the result (names and metadata, no values), which is the essential missing piece. For a simple read-only list tool with full schema coverage and rich annotations, that is sufficient for correct invocation.

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

Parameters3/5

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

Schema coverage is 100% and both parameters carry descriptions, including the explicit mcp_version instruction, so the schema does the heavy lifting. The description only echoes that app_id is the key input and adds no syntax or format detail beyond the schema.

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

Purpose4/5

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

States a specific verb and resource ('list backend secret names and metadata') plus a meaningful scope qualifier ('without revealing values'), so an agent knows exactly what it returns. It does not explicitly contrast with the write-side siblings (set_app_secrets, create_secret_entry, delete_app_secrets), leaving that inference to the reader.

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

Usage Guidelines4/5

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

Gives a clear invocation context ('Use this tool with app_id') and routes the agent to get_secret_entry_instructions for usage and workflow, which is real guidance rather than silence. It stops short of explicit when-not-to-use conditions against the secret-mutating siblings.

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

set_app_resourcesset app resourcesA

DestructiveIdempotent

Inspect

Call this tool to update an existing app's resources. Pass app_id and completed resource_upload_ids to replace matching paths, delete_paths to remove resources, or both. Applies live or stages into a failed source snapshot without starting deployment. Call get_resource_upload_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	Yes
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`delete_paths`	No
`resource_upload_ids`	No

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, openWorld=true, so the safety profile is covered. The description adds genuine context beyond them: it applies live or stages into a failed source snapshot and does not start a deployment — a real behavioral distinction. It does not disclose reversibility of deletions, batch limits (20 upload IDs / 500 paths), or partial-failure behavior, so it stops short of full transparency.

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

Conciseness4/5

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

Front-loads the action, then parameter usage, then behavioral caveat, then the pointer to instructions — a logical order with little waste. The trailing 'MCP version 2.12.' sentence is terse to the point of being cryptic without the schema, but it does serve the version parameter.

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

Completeness4/5

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

For a destructive mutation tool with annotations covering safety and no output schema, this tells an agent enough to invoke it: what it changes, both operating modes, and that it won't deploy. Gaps are the mechanics of path matching, partial failure, and whether deletions are recoverable.

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

Parameters3/5

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

Schema description coverage is only 25% (only mcp_version is documented), so the description must carry the load, and it does add meaning for app_id, resource_upload_ids ('completed'), and delete_paths. However it gives no format for the paths/IDs, no indication that resource_upload_ids is required-min-1 when supplied, and no note of the array caps.

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

Purpose4/5

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

States a specific verb+resource: update an existing app's resources, with the concrete mechanisms (replace matching paths, delete paths). It also points to get_resource_upload_instructions for workflow, which separates it from upload_resources and get_upload_status, though it doesn't explicitly name those siblings as alternatives.

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

Usage Guidelines4/5

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

Explains the two modes of use ('completed resource_upload_ids to replace matching paths, delete_paths to remove resources, or both') and defers the end-to-end workflow to get_resource_upload_instructions. What's missing is an explicit when-not-to-use (e.g., use upload_resources first to obtain upload IDs), which is only implied by 'completed'.

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

set_app_secretsBind submitted secrets to an appA

Destructive

Inspect

Call this tool with app_id and submitted secret_entry_ids to bind secrets to an existing app. Matching secret names replace stored values. Call get_secret_entry_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	Yes	Target app id
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`secret_entry_ids`	Yes	Submitted secret entry ids to bind to this existing app. Each entry contributes one secret name/value.

TDQS

A3.6/5.0

Behavior4/5

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

The annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety bar is lower. The description adds real behavioral detail beyond them: 'Matching secret names replace stored values,' which explains what is overwritten. It doesn't describe permission requirements or what happens on a name collision across different entries.

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

Conciseness4/5

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

The instruction (call this with X and Y to do Z) is front-loaded in the first sentence with no waste. The trailing 'MCP version 2.12' is terse but redundant with the mcp_version parameter description. Three short sentences, appropriately sized.

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

Completeness3/5

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

There's no output schema, so the description could have explained the return shape (success per entry, failures, resulting secret names) and hasn't. Annotations cover the safety profile and the description covers the overwrite behavior, but an agent learning the result of the call has to rely on the get_secret_entry_instructions pointer.

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

Parameters3/5

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

Schema description coverage is 100% — app_id, secret_entry_ids, and mcp_version are all documented in the schema, including the one-time, opaque nature of entry ids. The description adds only the replacement-by-name rule, which is a marginal addition over the schema. Baseline 3 applies when the schema carries this much load.

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

Purpose4/5

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

The description states a specific verb+resource: bind submitted secret entry ids to an existing app via app_id and secret_entry_ids. The scope (existing app, bound entries) distinguishes it from create_secret_entry and list_app_secrets. It stops short of explicitly naming those siblings, so it doesn't fully earn a 5.

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

Usage Guidelines3/5

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

It says to call the tool with app_id and secret_entry_ids to bind secrets, and it points to get_secret_entry_instructions for usage and workflow. But it never states when to avoid this tool or how it relates to delete_app_secrets / list_app_secrets. Usage guidance is implied and delegated rather than spelled out.

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

src_globList snapshot filesB

Read-onlyIdempotent

Inspect

Use this tool to find stored source paths for app_id. Optionally set version, path prefix, glob, include_dirs and continuation_token. Omitted version reads the latest attempted snapshot. MCP version 2.12.

Name	Required	Description	Default
`glob`	No	Glob pattern to match files (default: */)	*/
`path`	No	Directory path to search within
`app_id`	Yes	Target app id
`version`	No	Version to inspect. Omit to use the latest stored snapshot (last_attempt_version).
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`include_dirs`	No	Include directory paths in results
`continuation_token`	No	Token from previous response for pagination

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is low. The description adds one genuinely useful behavioral fact — omitting version reads the latest attempted snapshot — but says nothing about pagination behavior despite exposing a continuation_token, or about what happens when no snapshot exists.

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

Conciseness4/5

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

Two compact sentences front-load the core purpose and the key default. The trailing 'MCP version 2.12' is slightly redundant with the mcp_version schema field, but the overall text is tight.

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

Completeness3/5

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

For a 7-parameter read tool with no output schema, the description covers purpose and the version default but omits return shape (what a 'stored source path' entry looks like) and pagination semantics. It is adequate but has clear gaps an agent would hit in practice.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description merely enumerates the optional parameters and restates the version default already present in the schema, adding no format or syntax detail beyond it. Baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource: 'find stored source paths for app_id'. The agent can tell it retrieves path listings, but the description doesn't distinguish it from siblings like src_grep or src_read, leaving the file-listing vs content-reading boundary to be inferred.

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

Usage Guidelines3/5

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

Usage is implied by the optional parameters (glob, path prefix, include_dirs) and the note that an omitted version reads the latest snapshot. However, there is no explicit when-to-use-this-vs-src_grep/src_read guidance or precondition statement.

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

src_grepSearch snapshot file contentsA

Read-onlyIdempotent

Inspect

Use this tool to search stored source for app_id and a regex pattern. Optionally select version, path, glob and case_insensitive; control results with output_mode, context or before_context/after_context, line_numbers, max_file_size and continuation_token. Omitted version reads the latest attempted snapshot. MCP version 2.12.

Name	Required	Description	Default
`glob`	No	Glob pattern to filter files (e.g., '*.ts')
`path`	No	Directory path to search within
`app_id`	Yes	Target app id
`context`	No	Lines before and after (overrides before/after_context)
`pattern`	Yes	Regex pattern to search for (max 500 chars)
`version`	No	Version to search. Omit to use the latest stored snapshot (last_attempt_version).
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.
`output_mode`	No	content=matching lines, files_with_matches=file paths only, count=match count per file	content
`line_numbers`	No	Include line numbers in output
`after_context`	No	Lines to show after each match (0-20)
`max_file_size`	No	Max file size to scan in bytes (default 10MB)
`before_context`	No	Lines to show before each match (0-20)
`case_insensitive`	No	Enable case-insensitive matching
`continuation_token`	No	Token from previous response for pagination

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine context beyond that: the default-to-latest-snapshot behavior for omitted version, the 10MB default scan ceiling, the context-overrides-before/after precedence, and the MCP version stamp requirement. It does not disclose result ordering or pagination semantics beyond mentioning continuation_token.

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

Conciseness3/5

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

Purpose is front-loaded in the first sentence, which is good. The second sentence degenerates into a comma-separated inventory of parameter names that duplicates the schema, and the trailing 'MCP version 2.12' note is awkwardly placed without explaining why the agent must echo it.

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

Completeness3/5

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

With 14 parameters, no output schema, and annotations covering safety, the description is serviceable but thin on return values: it never says what a match record looks like, how counts are presented, or how continuation tokens are issued. The output_mode enum in the schema carries most of that burden, but a tool with no output schema would benefit from a sentence on result shape.

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

Parameters3/5

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

Schema coverage is 100%, so every parameter is already documented in the schema, including the context precedence rule and the version fallback. The description largely restates the parameter list rather than adding semantics, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('search stored source for app_id and a regex pattern'), which clearly separates it from mutation siblings like deploy_app or delete_app. It does not explicitly name the closest siblings (src_glob, src_read), so an agent must infer that grep searches content while read/glob retrieve files, but the core purpose is unambiguous.

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

Usage Guidelines3/5

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

It gives a real usage rule — 'Omitted version reads the latest attempted snapshot' — and implies the optional narrowing knobs. However, there is no guidance on when to use this versus src_glob or src_read, which is the most likely selection confusion among siblings, and no stated prerequisites for app_id validity.

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

src_readRead snapshot fileA

Read-onlyIdempotent

Inspect

Use this tool to read a stored source file by app_id and path (file_path is also accepted). Optionally set version, zero-based line offset and limit. Omitted version reads the latest attempted snapshot. MCP version 2.12.

Name	Required	Description
`path`	No	Path to the file to read. Required unless file_path is supplied.
`limit`	No	Number of lines to return (max 2000)
`app_id`	Yes	Target app id
`offset`	No	Line offset to start reading from (0-indexed)
`version`	No	Version to read from. Omit to use the latest stored snapshot (last_attempt_version).
`file_path`	No	Compatibility alias for path. Prefer path; if both are supplied they must match.
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world. The description adds meaningful context beyond them: the default-to-latest-snapshot semantics for omitted version and the alias resolution rule for file_path. No return format is described, but that is minor for a read tool.

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

Conciseness4/5

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

Three compact sentences, front-loaded with the core action and required identifiers. Every sentence carries information; the trailing 'MCP version 2.12' is slightly awkward but ties to the mcp_version parameter.

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

Completeness4/5

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

A read-only tool with full schema coverage and no output schema; the description covers the essential calling semantics including version defaulting and the path alias. Only missing piece is any hint about the shape of returned content.

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

Parameters3/5

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

Schema coverage is 100%, so all seven parameters are already documented. The description restates the offset/limit and version defaults and notes the file_path alias, but adds little beyond the schema's own descriptions.

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

Purpose4/5

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

States a specific verb and resource: 'read a stored source file by app_id and path'. Clear what it does, though it does not explicitly distinguish itself from siblings like src_glob or src_grep for file discovery/search.

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

Usage Guidelines3/5

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

Explains the optional version/offset/limit behavior and that omitting version reads the latest attempted snapshot. However, it gives no explicit when-to-use guidance versus src_glob or src_grep, leaving routing to inference.

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

upload_resourcesupload resourcesAInspect

Use this tool to collect binary app resources. For a new upload, declare resources with target_path and optional name, accept, required, purpose and preferred_source; optional app_id scopes it without changing the app. To resume, pass upload_id; add retry:true for a fresh transfer ticket. Source files are not accepted. Returns a widget and an external intake URL; offer both so the user can choose, and use the URL when the widget is unavailable. Call get_resource_upload_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`retry`	No	Request a fresh transfer ticket after a failed transfer, keeping the entry ID.
`app_id`	No	Optional app scope; uploading does not bind or deploy.
`resources`	No	Required for a new entry. Binary files under public/resources/ only.
`upload_id`	No	Resume an existing resource entry.
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare the mutation and open-world profile, and the description adds genuinely non-obvious behavior: the call does not upload bytes itself but returns a widget plus an external intake URL, both of which should be surfaced to the user, with the URL as the fallback. It stops short of explaining what state the created entry leaves behind or how it can be cancelled or cleaned up.

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

Conciseness4/5

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

The mode-selection guidance is front-loaded and each sentence carries information. Minor waste in the opening 'Use this tool to' framing, and the return-value guidance is buried mid-paragraph rather than surfaced early.

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

Completeness5/5

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

With no output schema, the description correctly carries the burden of describing the return value (widget plus intake URL) and how to present it. Combined with mode selection, the source-file exclusion, and the pointer to the instructions tool, an agent has everything needed to call it and act on the result.

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

Parameters4/5

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 mode-level meaning the schema cannot convey: resources is the new-entry path, upload_id the resume path, retry:true forces a fresh ticket, and app_id only scopes without binding or deploying. It also explains the 'MCP version 2.12' value that mcp_version expects.

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

Purpose4/5

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

States a specific verb and resource — collect binary app resources — and clarifies the constraint that source files are not accepted. An agent understands the intake flow, though the description never contrasts this with sibling set_app_resources, so the boundary between the two is left to inference.

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

Usage Guidelines4/5

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

Explicitly splits the two call modes: declare resources with target_path for a new upload, or pass upload_id to resume, with retry:true for a fresh ticket after a failed transfer. It also routes to get_resource_upload_instructions for the full workflow, but gives no explicit 'do not use when' condition or comparison against set_app_resources.

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

verify_custom_domainVerify a custom domainAInspect

Call this tool with app_id and domain to check DNS and advance an existing domain connection toward activation. Call get_custom_domain_instructions for usage and workflow. MCP version 2.12.

Name	Required	Description
`app_id`	Yes	Target app id
`domain`	Yes	Existing hostname to verify and activate
`mcp_version`	No	Set to "2.12", the MCP version in this tool's description. Use this tool's version, not another tool's version.

TDQS

A3.8/5.0

Behavior4/5

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

The annotations flag openWorldHint=true and readOnlyHint=false; the description adds real context beyond them, namely that this is a state-advancing mutation on an already-added domain rather than a pure DNS read. It does not explain what happens on verification failure or whether the operation is retried safely, so it falls short of a 5.

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

Conciseness4/5

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

Three short sentences, with the action and its scope front-loaded before the pointer to the instructions tool. The version trailer is boilerplate but earns its place because the schema requires that exact value.

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

Completeness3/5

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

No output schema exists, so the description should say what a verification call returns (for example, which DNS records are missing or the pending status), but it doesn't. It also leaves out prerequisites such as whether the domain must first be added or the app deployed.

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

Parameters3/5

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

Schema coverage is 100%, so app_id and domain are already fully documented. The description echoes both names and restates the mcp_version value ('2.12'), which is redundant with the schema's own instruction to set that same value, so it adds little beyond the schema baseline.

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

Purpose4/5

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

The description gives a specific verb and resource: it checks DNS and advances an 'existing domain connection' toward activation. Using 'existing' implicitly distinguishes it from add_custom_domain, though the sibling is never named directly.

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

Usage Guidelines4/5

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

It states the required inputs (app_id, domain) and routes the agent to get_custom_domain_instructions for the workflow. It doesn't say when the call will fail or when not to call it, so the condition is clear but the exclusions are absent.

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