Server Quality Checklist

Tool Scores

• snaphost_listC
  2.6/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions 'for the authenticated user' (auth scope) which is useful, but says nothing about whether this is read-only, what 'recent' means in time terms, how default pagination behaves, or what data is returned. Reads as a safe list operation but leaves behavioral details undisclosed.

  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?

  Single sentence, zero wasted words. It front-loads the verb and resource clearly. Concise without being under-specified to the point of tautology.

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

  Completeness2/5

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

  For a list-style tool with one self-documenting parameter, the description is mostly adequate. However, with no output schema and no annotations, it should disclose more about what the response contains (deploy IDs, timestamps, statuses?) and how 'recent' is bounded. A listing tool with sibling status/logs tools needs more context to avoid confusion.

  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?

  There is one parameter (limit) with 0% schema description coverage. However, the parameter is self-explanatory from its schema (integer, default 20, min 1, max 100) and name. The description adds no extra meaning about the limit parameter, which is acceptable given the schema already fully constrains it.

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

  Purpose3/5

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

  The description states 'List recent Snaphost deploys for the authenticated user' with a specific verb (list), resource (Snaphost deploys), and scope (recent, authenticated user). It's clear but doesn't distinguish from siblings like snaphost_status or snaphost_logs, which could overlap in purpose.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this vs alternatives. The sibling tools (snaphost_deploy, snaphost_logs, snaphost_delete, snaphost_status) have potentially overlapping functionality but the description provides no exclusions or differentiation cues for when listing deploys is preferred over checking status or logs.

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

• snaphost_deleteB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Delete' implies destructive behavior, which the agent can infer, but the description doesn't state reversibility, permission requirements, what happens to associated data/logs, whether the action is idempotent, or confirmation of successful deletion. For a destructive operation with zero annotation coverage, this is thin.

  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, efficient sentence with no filler or redundancy. The phrase 'frees its URL' adds a useful clarifying consequence in parens. It's appropriately sized for a simple one-parameter tool, though it could arguably add one clause about behavior without hurting conciseness.

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

  Completeness2/5

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

  This is a destructive operation with no annotations, no output schema, and 0% schema coverage. The description tells the agent the what (stop and delete) but omits critical operational details: whether deletion can be undone, how to confirm success, what errors to expect (deploy not found, already deleted), and side effects on associated resources. For a deletion tool, this is meaningfully under-specified.

  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?

  With schema description coverage at 0%, the description does nothing to clarify the deploy_id parameter. However, there is only one parameter and the name 'deploy_id' plus the schema's uuid format make its purpose reasonably self-evident. The description provides no additional semantic meaning (such as where to find the ID, format expectations, or validation rules) beyond what the schema gives.

  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 uses a specific verb-resource structure: 'Stop and delete a Snaphost deploy (frees its URL).' It clearly names the resource (deploy) and the actions (stop and delete), plus the consequence (frees URL). This distinguishes it from siblings like snaphost_deploy, snaphost_logs, and snaphost_status without being tautological.

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

  Usage Guidelines2/5

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

  The description states the action but gives no guidance on when to use it vs alternatives. It doesn't mention prerequisites (e.g., deploy must exist, must be in a certain state), whether it works on active vs already-deleted deploys, or any exclusions. It only explains what happens (frees URL) but not when or when-not to use it.

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

• snaphost_logsA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden for behavioral disclosure. It mentions pagination state via 'next_since', which is useful, but it doesn't mention whether logs are append-only, whether older logs get truncated, timeouts for log availability after deploy, or rate limits. For a read-only log-fetching tool, the disclosure is adequate but not rich.

  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 two compact sentences with zero waste, front-loading the core purpose first and immediately following with the critical pagination usage detail. Every word 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?

  For a simple two-parameter read tool with no output schema, the description is reasonably complete. It explains the purpose, the required identifier, and the paging mechanism. It could optionally clarify return format or log ordering, but given the low complexity and small parameter count, this is largely sufficient.

  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 50% (deploy_id is described only by its format; since has a description). The description adds the pagination relationship between 'since' and 'next_since' that the schema doesn't capture, which is valuable. However, deploy_id's semantics (which deploy's logs) are implied by the description but not enriched 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 it fetches 'build/runtime logs for a Snaphost deploy' with a specific verb and resource. It distinguishes the use case (logs retrieval) from siblings which handle deploy/delete/status/list operations, though the scope of what logs contain and the distinction from status is implicit rather than explicit.

  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?

  The description provides clear context for the 'since/next_since' pagination pattern ('Pass next_since from a previous call to page'), which guides sequential usage. However, it doesn't explicitly state when to use this vs alternatives like snaphost_status, though the log-fetching purpose is reasonably self-evident.

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

• snaphost_statusA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose that the tool returns a URL 'when running', which is useful context. However, it doesn't state whether this is a read-only operation (though the name/description implies retrieval), whether it blocks/polls, or what it returns when not running. For a status-check tool, some of these gaps are notable, though the 'when running' note earns partial credit.

  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?

  A single, tight sentence that conveys purpose plus the key behavioral note about URLs. Zero wasted words, front-loaded with the verb and resource. Nothing extraneous.

  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 one-parameter status-check tool with no nested objects and no output schema, the description is reasonably complete. It covers purpose and the key running-state behavior. It could note edge cases (e.g., what happens for a non-existent deploy_id) and doesn't describe possible status values, but given the tool's low complexity, this is a minor gap rather than a fatal one.

  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?

  There is only one parameter (deploy_id) with 0% schema description coverage. However, with just one UUID-typed parameter and a clear tool purpose, the meaning is largely self-evident: the ID of the deploy whose status to query. The description 'of a Snaphost deploy' reinforces that the ID refers to a deploy resource. The low schema coverage is acceptable here because the single param's semantics are obvious given the simple tool context.

  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 clearly states the verb ('Get'), resource ('status'), and adds the useful parenthetical that it returns the URL when running. It distinguishes itself from siblings: snaphost_deploy (create), snaphost_delete (remove), snaphost_logs (logs), snaphost_list (list). 'Status' clearly maps to a health/state-check operation, distinguishing it well.

  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?

  The description implies this is used after a deploy to check its state, which is reasonable usage context. However, it doesn't explicitly state when to use this vs the sibling tools (e.g., when you'd pick status over logs or list). No exclusions or alternative guidance are named.

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

• snaphost_deployA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.