bitpull_publish_site

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

Annotations only supply destructiveHint=false, so the description carries the real weight and does so well: it discloses an implicit build step, a required human confirmation, and an asynchronous job model that must be polled via site_job. What it omits is whether the publish is immediately live, how long jobs typically take, and what authorization/account linkage is assumed.

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

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

Three short sentences, front-loaded with the action and destination, then the confirmation requirement, then the return-and-follow-up contract. Nothing is redundant and the async polling instruction arrives before the agent would need it.

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 only a thin annotation, the description covers the essentials an agent needs: side effects, human gate, and the job/polling contract via site_job. It leaves open prerequisites such as whether a site record must already exist and how failures surface, but it is sufficient to invoke the tool correctly.

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

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

Schema coverage is 50%: folder is documented inline as an absolute path, while provider is a bare enum with no description in the schema. The description partially compensates by explaining that Cloudflare or Vercel means the person's own account, but it adds no meaning to folder beyond the schema and gives no guidance on choosing between the two providers.

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 ('Publish a site folder') plus the destination ('the person's own Cloudflare or Vercel account'), which separates it from generic publish/deploy siblings. It stops short of naming how it differs from neighbors like prepare_publish or publish_repo, so the agent must infer the split.

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?

'Puts it on the internet: the person confirms' establishes the human-confirmation precondition, and 'follow it with site_job until it gives the address' prescribes the exact follow-up path. There are no explicit exclusions or named alternatives, so an agent still has to guess when prepare_publish or publish_repo would be the better call.

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