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.