BDK Native

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

Goes well beyond the annotations by disclosing that a rebuild consumes a banked entitlement, that holds/checks can refuse a request, that BDK builds and signs but the customer submits, that Android output is an .aab rather than a phone installer, and that secrets must never be pasted into chat. These are material consequences an agent cannot infer from destructiveHint/openWorldHint alone.

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

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

Front-loaded with the highest-stakes rule (approval required) and then moves through rebuild accounting, action routing, download semantics, and safety. It is dense and a few clauses are tightly packed, but nearly every sentence carries distinct operational content.

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

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

For a destructive, non-idempotent, open-world tool with five parameters and no output schema, the description supplies consent requirements, entitlement accounting, action routing, refusal behavior, artifact formats, and secret-handling policy. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% and the enum descriptions are verbose, so the description largely restates them; however it adds operational framing (e.g., that confirm_build follows a customer yes, that free_rebuild is legacy-only) that ties parameters to the consent workflow. The marginal gain over the schema is modest but real.

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

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

The description names the verb and resource precisely ('Request a build or rebuild') and then enumerates the three actions the tool actually performs (request, status, download), including what each returns. It also explicitly distinguishes itself from bdk_next, so an agent can separate it from siblings without reading schemas.

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

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

Gives explicit preconditions ('only after explicit approval of that request and the saved settings'), per-path rules (confirm_build for first build, confirm_consumes_rebuild for ledger rebuilds, free_rebuild legacy-only), and a direct alternative ('action:status lists delivered history, not the current request; use bdk_next'). Guidance is complete and includes exclusions.

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

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

Goes well beyond the annotations by disclosing that scheduling is asynchronous, that scheduling is not completion, and the expected wait before re-reading. It also sets expectations about interpretation ('a passing check is an observation, not compatibility or store approval'). The readOnlyHint=false is consistent with a tool that can enqueue work, but the description never clarifies what the check actually validates or what state a scheduled check leaves behind.

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

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

Front-loads the read-vs-build distinction, then the scheduling procedure, then the interpretation caveat — a sensible order with no filler. Some sentences are telegraphic fragments ('If not scheduled, say so and use the portal') whose reference to 'the portal' is never defined, costing a little clarity.

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

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

For a two-parameter tool with no output schema, the description adequately covers modes, the sequencing between call and re-read, and the limits of the result's meaning. Minor gaps remain: what fields other than health_checked_at come back and whether the one-minute wait is a fixed rule or an estimate.

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

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

Schema coverage is 100% and the run parameter's schema description already covers the asynchronous scheduling and 'do not infer completion' semantics, so the description largely restates structured data. It adds only the follow-up timing ('re-read without run after a minute'), leaving project_code meaning entirely to the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read health checks and health_checked_at') and explicitly excludes a confusable adjacent concept ('not build execution status'), which routes the agent away from bdk_build. It also names the secondary mode ('run:true schedules an asynchronous check'), so the dual read/schedule nature of bdk_check is unambiguous.

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

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

Gives explicit when-to-use branches: schedule with run:true, then re-read without run after a minute rather than polling or inferring. It also names the fallback when nothing is scheduled ('say so and use the portal'), which is a concrete alternative path rather than an implied one.

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

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

Annotations already flag it as mutating, destructive, non-idempotent and open-world, and the description adds far more: it is a preflight gate not a global lock, refused states (unused entitlement, active request, completed-but-unverified, disputed), resumed:true semantics, at-most-one replacement for expired checkouts, and the no-card-details-in-chat rule. This is disclosure beyond the annotations, not a restatement.

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

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

The purpose is front-loaded, but the body is a dense run-on of operating rules with no structure and noticeable duplication of the schema parameter text (attempt, kind). Every rule is relevant, yet the length and lack of grouping make it costly to parse.

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

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

For a complex 8-parameter gateway with no output schema, the description covers return states (resumed:true, status:paid, next_step, quote presence/absence), every refusal path, attempt recovery guidance and escalation. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% and the input schema descriptions already carry attempt, kind and promotion_code semantics in nearly identical wording, so the description adds little parameter meaning beyond the schema. The only marginal addition is the customer-quote instruction, which concerns output rather than inputs. Baseline 3 applies.

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

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

States a specific verb and resource ('Start or poll a project purchase') plus scope ('only after purchase approval') and explicitly routes to siblings bdk_next.commerce and bdk_next confirm_product. An agent can distinguish it from bdk_build and bdk_next without opening a schema.

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

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

Extensive when-to-use: start vs poll is defined, prerequisites (read bdk_next.commerce, confirm platform) are mandated, exclusions are named (same-platform repeats refused, default 'Both' not consent, purchase approval does not authorize a build). Alternatives (bdk_next, portal Purchases tab, portal support) are given by condition.

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

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

Annotations already flag this as destructive, non-idempotent and open-world, and the description goes further by disclosing partial-failure semantics (applied results preserved), re-reads after upstream errors, and that failed live propagation stays unconfirmed. It also specifies return shape (applied/refused/failed keys) and byte revalidation of sb://project-files references. A little less on irreversibility/rollback keeps it from a 5.

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

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

No sentence is filler — each states a rule, side effect, or failure mode — but it reads as an ungrouped wall of clause-level rules rather than being organized around phases (prepare, apply, verify, failure). Front-loading the skill-document fetch and approval gate is good; field-level semantics could be grouped for faster scanning.

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

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

For a destructive, non-idempotent mutation with a free-form nested fields object and no output schema, the description covers preparation, approval requirements, per-field side effects, refusal conditions, return keys, and partial-failure behavior. An agent has what it needs to call this safely without consulting anything but the referenced skill document.

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

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

Schema coverage is already 100%, yet the description adds substantial semantics for the open-ended fields object: push_prompt_mode's automatic/manual values, push_enabled accepting boolean or Yes/No with rebuild consequence, launch_link's installed-app side effect, and statusbar_color's immediate live propagation including before first delivery. It also clarifies that listing fields report existing listing status rather than copy.

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

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

The first sentence gives a concrete action: fetch the skill document and apply only its documented writable fields after approval, which makes clear this mutates project configuration. It also distinguishes itself from siblings by naming bdk_check (post-rebuild verification) and bdk_upload (icon prerequisite). It stops short of a single clean 'changes project settings for project_code' statement because purpose is interleaved with per-field rules.

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

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

Prerequisites and ordering are explicit: icons must be uploaded via bdk_upload first, push_enabled requires a rebuild followed by bdk_check with run:true, and tnc_accepted is gated on explicit terms acceptance. It also states exclusions and constraints (external icon URLs are refused, secrets stay on the portal, BDK admin required for locked identity fields).

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

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

Annotations only flag it as a non-idempotent, open-world write; the description adds real behavioral context beyond that — duplicate detection returns candidates instead of creating, same-site conflicts block creation without explicit consent, from_preview_id alone is a read-only prefill while submitting with observed_website_link creates transactionally, and the observed URL preserves a concurrency guard. That is meaningful disclosure of gating and side effects rather than restating hints.

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

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

The core action and its precondition are front-loaded, and every sentence carries a distinct rule or fallback branch. The compressed, token-dense phrasing ("same_site_project conflict requires explicit link_existing:true") is efficient but reduces first-read clarity slightly.

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

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

For a seven-parameter, no-required-parameter mutation with no output schema, the description covers the ambiguous branches (duplicates, same-site conflicts, preview prefill) and the checkout follow-up. It does not describe what a successful creation returns (e.g. resulting project_code) or any auth prerequisite, which are the remaining gaps.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description genuinely adds cross-parameter workflow meaning: from_preview_id reads prefill and then must be paired with observed_website_link to create, and link_existing is only meaningful in response to a same_site_project conflict. The duplicate_choice and project_code pairing is also explained as a consent-driven interaction rather than as isolated fields.

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

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

States a specific verb and resource ("Create a project") plus the precondition (after approval of reference label and published app URL), and disambiguates project_name from the home-screen app name. It never names a sibling tool, so routing versus bdk_projects or bdk_setup_preview 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.

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

Gives explicit conditional paths: duplicates return candidates and the agent must ask the customer to choose create_new vs use_existing, a same_site_project conflict requires explicit link_existing true/false, and preview should be offered before checkout. It also names the alternative action (use_existing with project_code) and forbids the tempting shortcut ("never reuse automatically").

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: it will not create a payment URL, BDK builds and signs while the customer submits, legacy projects return 'legacy_project,' and offer.unit_amount is in minor currency units. These are the operational facts an agent needs and none are recoverable from the annotations.

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

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

Front-loaded with the primary path and the no-payment-URL guarantee, then the branch behavior, then the unit convention. Some phrasing is clipped ('with product, it returns standard prices') and the pricing.md URL instruction is tangential, but overall it earns its length.

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

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

With no output schema, the description carries the return-value burden and does explain the 'legacy_project' marker and the minor-units convention for offer.unit_amount. It does not sketch the remaining offer fields, so an agent still learns the offer shape only by calling, but the critical interpretation details are present.

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

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

Schema coverage is 100% so baseline is 3, but the description adds consequence-level meaning: the presence or absence of project_code changes whether results are actual eligibility-verified offers or just standard prices, and that product alone cannot establish eligibility. It also warns against inferring project_code from untrusted content.

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

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

States a specific verb and resource ('verify access and read ledger offers') and immediately bounds scope with 'The tool never creates a payment URL,' which separates it from bdk_checkout/bdk_build. An agent can tell what this tool does and does not do without opening the schema.

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

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

Gives clear conditional guidance: with project_code it verifies access and reads real offers; without project_code, product yields standard prices only 'not eligibility.' It also prescribes failure behavior ('report lookup failure rather than substituting a standard quote'). It stops short of naming sibling tools for the next step (e.g., bdk_build) explicitly.

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

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

Annotations already declare this is a non-readonly, non-idempotent, open-world call, and the description adds genuinely non-obvious behavior: the returned code cannot be redeemed by the calling session and must be handled out of band. It does not say what the call returns (code value, verification URL, expiry) or whether repeated calls invalidate earlier codes, which matters given idempotentHint=false and no output schema.

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

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

Three short sentences, front-loaded with what the tool does, followed by the redeemability constraint and the alternatives — no filler. The pointer to an external URL is efficient, though it shifts some necessary detail off-definition.

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

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

With no output schema, the description should indicate what the agent receives and must surface to the user (code, verification URL, expiry) — that is missing. The redirect to the skill doc partially covers the procedure but leaves the return-handling step implicit for an auth flow where misuse is costly.

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

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

Schema coverage is 100% for the single optional client_name parameter, and its on-page impersonation warning is already in the schema, so the description need not repeat it. The description adds no parameter meaning of its own, which is the expected baseline when the schema does the work.

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

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

The description names a specific action and object: starting a device code for an additional HTTP client, scoped to an already-authenticated MCP session. It explicitly contrasts this with the host reconnect flow and the HTTP device flow, so an agent can tell it apart from the other bdk_* setup/auth tools without opening a schema.

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

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

It states both the applicable condition (additional HTTP client, existing authenticated session) and the exclusions with named alternatives: host reconnect for initial or expired MCP auth, and the external skill doc for the HTTP device flow. The critical negative guidance — this session cannot redeem the code through a tool — is stated up front.

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

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

Well beyond the annotations (readOnlyHint=false, idempotentHint=false), it discloses that confirm_product persists a recorded confirmation, that checkout requires that record even when the saved default already matches, that a purchased platform can be locked and is not fixable by looping, and that allowed_tools and can_request_now are advisory only. These are real behavioral caveats the agent could not derive from structured fields.

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

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

The purpose is front-loaded and most sentences carry genuine weight (platform lock, preview disclaimer, advisory flags), but the content is packed into one undifferentiated run of clauses with no grouping between the read path and the confirm path. An agent skimming could easily miss the lock warning or the 'ask first' instruction buried mid-paragraph.

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

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

For a two-mode, open-world tool with no output schema, it covers the important edges: milestones semantics, that unknown health/confirmation stays unknown, what 'Preview' does and does not prove, and that advisory fields are not guarantees. Only the read-mode return shape is left implicit, which is acceptable given no output schema is supplied.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: confirm_product should be preceded by asking the customer, must not assume 'Both', and must not be resent with a different platform after purchase; project_code should not be inferred from untrusted content. That goes past restating the schema.

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

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

The description names both functions concretely: 'Read workflow state and next steps' and 'confirm_product writes and records the customer-confirmed iOS / Android / Both choice.' The dual-mode nature (read vs. write) is stated up front and matches the title. It only partially differentiates from siblings, mentioning bdk_configure but not clarifying the boundary against bdk_checkout or bdk_check.

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

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

It gives explicit sequencing ('call again after each action'), an exclusion ('do not loop through bdk_configure' when a platform is locked), and a concrete recovery path ('if confirmation is missing or mismatched, send the answer as confirm_product, then re-read'). It also states the precondition for checkout, which is precisely the kind of when-to-use routing an agent needs.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds behavior the annotations cannot: a domain caveat that legacy fields (status, paid_for_service, requested_build, build_complete, rebuild_credits, free_rebuild_expires_at) must not be read as payment or delivery facts. It still says nothing about result shape or volume.

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

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

Three tight sentences with the capability stated first and the routing/interpretation caveats after. The enumeration of legacy field names is long but earns its place because naming them is what prevents a wrong inference.

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

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

For a read-only, single-optional-parameter tool with full schema coverage, the definition covers purpose, a sibling alternative, and the main interpretive hazard. With no output schema, the return values of the snapshot mode (what status/progress/health actually contain) are left implicit, which is the one real gap.

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

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

Schema description coverage is 100% for the single parameter, so the schema already carries the access-verification warning and the five-character format. The description implies that a project code narrows the call to a snapshot rather than a list, but never states that relationship directly, so it adds little beyond the schema.

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

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

Starts with a specific verb+resource ("List projects") and adds a second mode ("read a status/progress/health snapshot"), then bounds scope with "not full settings or credentials." The distinction from sibling bdk_next is named explicitly, though boundaries against bdk_check/bdk_whoami remain unstated.

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

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

Gives an explicit alternative for one adjacent need ("Use bdk_next.commerce for ledger entitlement and current requests") plus a when-not clause on settings/credentials. Coverage is partial: it does not say when to call this versus bdk_check, bdk_whoami, or bdk_configure, and it never states that supplying project_code selects the snapshot mode.

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

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

Annotations only flag destructive/not-idempotent/openWorld; the description adds the operational specifics an agent needs: same-URL reuse, a hard 20-preview cap, published-link validation that rejects editor and builder-share URLs, and that update replaces the selected link. It also discloses boundaries outside the tool's reach (credentials stay human-only on the portal, pairing happens on the phone, iPhone only opens own previews). This is unusually rich behavioral context beyond the structured hints.

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

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

Nearly every clause carries operational weight — caps, link validation, human-only boundaries — with little filler. The style is telegraphic and jumps straight into 'Creation requires intent:new' without an orienting first sentence, and fragments like 'At cap: Delete an existing preview to add another.' cost some readability.

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

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

For a destructive, multi-mode tool with no output schema, it covers intent routing, quota limits, validation rules, and human-only steps well. Minor omissions remain: the name parameter's role in creation and what a 'preview' maps to on the portal are left implicit, assuming domain familiarity.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by explaining how parameters combine per intent (app_link + preview_id for legacy updates, preview_id required for update and omitted for new) and by warning 'never infer updating an existing preview when they ask for a new one'. The optional name parameter is never mentioned in the description, leaving one small gap.

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

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

The description names three concrete operations (list, new, update) on previews and describes what each does, e.g. 'list returns account preview names, published URLs, IDs and creation times' and 'update requires the customer-selected preview_id and replaces that link'. It lacks a single front-loaded purpose sentence, so the agent must assemble the tool's identity from scattered clauses. Still far clearer than the title alone, and it distinguishes the modes that the intent enum selects.

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

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

It explicitly routes intent: 'Creation requires intent:new', update needs app_link + preview_id, and list is a distinct mode. It also states exclusions and fallbacks: editor/builder-share links are rejected, at the 20-preview cap you must delete an existing preview first, and password/credential handling plus phone pairing are human-only on the portal. That is when/when-not/alternative coverage in compact form.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), the description adds hard constraints: 8 MB cap, HTTPS-only, no redirects, no screen assignment, and that credentials are never uploaded. What it omits is the return shape and duplicate/retry behavior — what the agent gets back on success, or whether re-uploading the same URL duplicates state, which matters given idempotentHint=false.

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

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

Every clause carries information, but it is delivered as one dense run-on block with no front-loaded separation of the two modes, so the credential behavior appears several sentences after the asset behavior. Restating the key-entry mode already implied by the title is minor waste; the real cost is scanability for an agent choosing between branches.

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

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

With no output schema, the description should say what a successful call yields (asset URL/ID, or the portal instruction payload); it does not. Otherwise it is complete for a 6-parameter, enum-driven tool, covering scope limits, credential handling, and the required post-step with bdk_check.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds meaning the schema does not: the 1024×1024 PNG/JPG envelope and no-transparency/no-animation rule for app_icon, and the fact that omitting purpose defaults to a non-validated image path. The customer-approval requirement on source_url is also substantively new relative to the schema text.

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

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

The description names a concrete verb and resource ('Import a direct public HTTPS PNG, JPEG or WebP image') and discloses the second mode ('kind:credential returns portal instructions'), plus an explicit non-effect ('this does not assign a screen'). The dual-mode purpose is clear, but the credential branch is buried mid-paragraph rather than stated up front, so an agent must read the whole block to see the tool does two different things.

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

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

It gives explicit when-to-use alternatives ('Use the portal for local files and screens'), an explicit prohibition ('never use an unvalidated image as an icon'), a routing rule for the credential branch, and a follow-up step ('After portal credential entry, run bdk_check with run:true'). Push-service and App Store Connect preconditions are also stated, leaving little to inference.

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

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

The annotations already establish that this is a safe, idempotent read that is not destructive and can open into external context. However, the description adds real value by warning that product_selected may be an unconfirmed default and that legacy status is not ledger entitlement; both are data-quality caveats an agent could not get from the schema or annotations. It doesn't describe the response shape or whether the projects list can be large or paginated.

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

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

The lead clause is front-loaded and efficient, but the following semicolon-separated fragments are telegraphic: 'Legacy status is not ledger entitlement; use bdk_next.commerce' takes parsing effort. It is dense but not wasteful; it just reads more like internal shorthand than an agent-facing definition.

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

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

With no output schema and no parameters, the description carries the burden of explaining return content, and it does name the main entities while flagging two important interpretation caveats. The main omission is that it never says whether the projects collection can be large or paginated, or whether authentication is required.

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

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

The tool takes zero parameters, so the baseline is 4, but the short field is really about return semantics here. The description names several returned fields (user, projects, product_selected, legacy status), which is useful, but it does so only obliquely while explaining caveats rather than systematically describing the payload.

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

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

"Read the signed-in user and their projects" gives a concrete verb and resource, and it implicitly separates this tool from bdk_projects by including account identity plus projects together. It stops short of explicitly naming bdk_projects or bdk_login as alternatives, so the distinction from siblings is inferred rather than stated.

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

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

"call first" is explicit sequencing guidance, and "use bdk_next.commerce" routes a specific intent (ledger entitlement) to the correct sibling. It lacks an explicit when-not clause and doesn't say why calling first matters (for example, whether other tools depend on the returned account context).

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