snaphost_deploy

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

With no annotations provided, the description carries the full burden of disclosure, and it does well: it reveals it costs vibecoins, packs with ignore-file respect, drops node_modules/.git/.env, auto-generates Dockerfile when absent, requires PORT listening when a Dockerfile is present, and can wait up to 15 min. This is rich, actionable behavioral detail far beyond what a bare schema would convey. Minor gap: no mention of what errors or failure modes look like.

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

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

The description is a single, information-dense paragraph that front-loads the core action and flow, then packs the critical warnings (no Dockerfile needed, PORT requirement) at the end. Every sentence earns its place. It's slightly long but justified given the critical deployment constraints that prevent deployment failures. No filler.

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

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

Given a moderate-complexity deploy operation with only 2 well-documented params and no output schema, the description covers the key operational facts: packaging behavior, cost, Dockerfile rules, PORT requirement, and wait semantics. The only gaps are the absence of explicit failure modes or what the public URL format looks like, but this is reasonably complete for guiding a first deploy.

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% — both parameters (path, wait) are already documented in the schema with descriptions. The tool description itself doesn't add parameter-level meaning beyond what the schema provides, so baseline 3 applies. The description implies wait behavior ('waits, and returns the public URL') which aligns but adds no new syntax or format detail.

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

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

The description clearly states 'Deploy a local project folder to Snaphost' with specific verb (deploy) and resource (project folder to Snaphost). It enumerates the full end-to-end flow (pack, upload, build, wait, return URL), which distinguishes it from sibling tools like snaphost_delete (teardown), snaphost_status (inspect), and snaphost_logs (observe). The deploy action is unambiguous and distinct.

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

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

The description gives strong contextual 'when' guidance via the critical warning: 'do NOT create a Dockerfile before deploying' — an explicit prohibition. It also clarifies the platform auto-generates a Dockerfile if none exists. However, it doesn't explicitly contrast against sibling tools or state when deploy should NOT be used (e.g., 'if you just need to check status, use snaphost_status'). The exclusions are behavioral rather than comparative.

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