Upfling provides a zero-configuration environment for hosting static websites. You can upload individual HTML, CSS, and JS files or drag an entire folder to receive a live website with SSL on a shareable URL in seconds. It eliminates the need for complex setup or server configuration, focusing on rapid deployment for static web projects.
You can also upload documents like PDFs and add password protection.
All of this can be done using the API or MCPs from AI chat platforms.
Scored across 15 tools
Core CRUD tools are mostly distinct, but there are boundary overlaps: `fetch` can return both site summaries and file contents, duplicating `get_site` and `read_site_file`, and an empty `search` query overlaps with `list_sites`. `create_site` vs `request_upload` without a site_id is disambiguated by file size, though the two creation paths still require careful reading.
Most tools follow a clear verb_object snake_case convention (`create_site`, `delete_site_files`, `replace_site_files`). Minor inconsistencies exist: bare verbs `fetch` and `search` don't include an object, and `read_site_file` uses `read` while site-level retrieval uses `get`.
15 tools is near the upper edge of the ideal 3-15 range but reasonably covers sites, files, uploads, search, and account info. A few tools (`fetch`, `search`) overlap with existing getters/listers, so the count could be trimmed slightly without losing functionality.
The main site and file lifecycle is covered: create, read, update, delete, upload, search, and account checks. Gaps include no restore or trash tool even though `delete_site` promises recoverability, no custom domain update operation, and no way to abort an upload batch after `request_upload`.
Finalize a batch of uploads after the caller has PUT all file bytes to the presigned URLs returned by request_upload. The site goes live (or is updated) only after this call succeeds. All files in the batch are published atomically.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | The site's public identifier returned by list_sites or create_site. | |
| upload_id | Yes | The batch upload_id returned by request_upload. Covers all files in that call. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: atomic publication of all files and the fact that the site goes live or is updated only after success. This complements the idempotentHint and destructiveHint annotations without contradicting them.
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 sentences, each earning its place: the precondition, the effect on the site, and the atomicity guarantee. The most important information is front-loaded and there is no redundancy or 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 that an output schema exists and annotations cover idempotency and safety, the description provides all necessary behavioral context: the required preceding step, the publish effect, and atomicity. Nothing critical is missing for an agent to invoke this 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 description coverage is 100%, so the schema already fully documents both site_id and upload_id. The description does not add parameter-level meaning beyond what the schema provides, so the baseline score of 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?
The description clearly states a specific verb ('Finalize') and resource ('a batch of uploads'), and explains the relationship to request_upload. It distinguishes itself from the sibling tools by specifying that the site goes live only after this call succeeds.
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 states the precondition: the caller must have PUT all file bytes to the presigned URLs returned by request_upload. This gives clear when-to-use guidance, though it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new site with inline text files (HTML, CSS, JS, SVG, JSON, etc.). For large or binary files, use request_upload without a site_id instead — it creates the pending site and upload batch in one operation. Inline limit: 200 files, 1 MB per file.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Files to deploy inline. Each entry is a path + UTF-8 content string. Must contain at least one file. | |
| title | No | Display name for the site in the dashboard. Optional. | |
| password | No | Password-protect the site. Requires Lite plan or above. Optional. | |
| subdomain | No | Requested subdomain for the site URL (e.g. 'my-portfolio'). Optional — Upfling assigns one if omitted. Must be lowercase alphanumeric and hyphens only. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| status | Yes | |
| warnings | No | |
| subdomain | Yes | |
| upload_slots | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide generic false hints for readOnly and destructive, which don't add much. The description compensates by explaining the inline operation and its limits, but doesn't disclose details like authentication needs or what happens on failure. However, with annotations being sparse, the description does a decent job.
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 concise, front-loads the core purpose, and uses a clear alternative instruction within two sentences. No wasted words.
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?
The tool is moderately complex with 4 parameters and an output schema exists, so return values are covered. The description provides the key usage distinction and limits, but could mention that the operation is not idempotent (annotations already indicate false, but description doesn't add behavioral nuance). Overall, complete enough for correct invocation.
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%, so all parameters are already well-documented. The description adds minor context about the 'files' parameter (inline vs. upload) but doesn't go beyond 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?
The description clearly states the verb 'create', the resource 'site', and the method (inline text files). It distinguishes itself from sibling tools by naming specific alternatives like 'request_upload' for large/binary files. The mention of inline limits adds scope precision.
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 explicitly says when to use this tool vs. alternatives: 'For large or binary files, use request_upload without a site_id instead'. It also provides clear constraints (inline limit: 200 files, 1 MB per file) that inform usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a site. By default the site is moved to trash and can be recovered. Pass permanent: true to delete immediately and permanently — this cannot be undone.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | The site's public identifier returned by list_sites or create_site. | |
| permanent | No | If true, permanently delete the site and all its files. Cannot be recovered. Default false (moves to trash). |
| Name | Required | Description |
|---|---|---|
| deleted | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal destructiveness, but the description adds crucial nuance: default deletion is recoverable via trash, while permanent: true is immediate and irreversible. This goes beyond the scalar hints and gives the agent the safety-relevant behavioral context it needs.
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?
Two sentences with no filler. The core action is front-loaded, and the destructive warning is placed immediately after the default behavior. Every sentence earns its place.
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 full schema coverage, a rich output schema, and destructive annotations, the description covers the essential behavior and the irreversible edge case. Nothing an agent needs to call it correctly 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 description coverage is 100%, so the schema already documents both site_id and permanent in full detail. The description restates the permanent behavior rather than adding new parameter-level meaning, so the baseline of 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: 'Delete a site.' The description distinguishes this from delete_site_files by targeting the site object itself, and clarifies two clear modes (trash vs. permanent). An agent can identify what this tool operates on without ambiguity.
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 guidance on when to use the permanent flag vs. the default trash behavior, which is the main decision point. It does not explicitly compare against sibling tools like delete_site_files, but the object-level scope is clear from the description and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific file from a site. The site stays live; only that one file is removed.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path of the file to delete, e.g. 'old-page.html'. | |
| site_id | Yes | The site's public identifier returned by list_sites or create_site. |
| Name | Required | Description |
|---|---|---|
| deleted | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructive (destructiveHint: true) and idempotent (idempotentHint: true) behavior. The description adds valuable context by specifying that the site stays live and that only the specified file is removed, which clarifies the exact scope of destruction beyond the generic annotation. It does not contradict any annotation.
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, front-loaded sentence that efficiently conveys the action and its key effect. It has zero wasted words and immediately states what the tool does and its scope.
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 simple destructive tool with two well-documented parameters, the description covers the essential behavioral aspects: it deletes a specific file, leaves the site live, and is idempotent (per annotations). The presence of an output schema reduces the need to describe return values. It could mention irreversibility explicitly, but the destructive annotation already conveys that. Overall, it is sufficiently complete for an agent to call it 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 description coverage is 100%, with both parameters (site_id and path) having clear descriptions. The tool description does not add any additional meaning about the parameters, so it remains at the baseline of 3. It neither enriches nor contradicts 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 states a specific verb ('Delete'), a resource ('a specific file from a site'), and explicitly clarifies that only that one file is removed while the site stays live. This clearly distinguishes it from the sibling tool delete_site, which deletes the entire site, and from file-related tools like read_site_file or write_site_files.
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 provides clear context that this tool is for removing a single file without affecting the site's overall availability. It implies when to use it versus delete_site by clarifying the site remains live, but it does not explicitly name alternative tools or state when not to use them. This is a minor gap, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one search result by id. 'site:' returns a readable summary of the site (title, live URL, status, storage, dates, first 100 files). 'file::' returns the file's content as UTF-8 text when it is a text type of at most 1 MB, otherwise a short note pointing at its live URL. Returns {id, title, text, url, metadata}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | An id returned by search: 'site:<site_id>' for a site summary, 'file:<site_id>:<path>' for a file's content. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| text | Yes | |
| title | Yes | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations by disclosing conditional behavior: site ids produce a readable summary with specific fields, file ids return UTF-8 text only for text types at most 1 MB, otherwise a short note pointing to the live URL. It also states the return shape. This is rich behavioral context consistent with the readOnly and idempotent 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?
The description is compact and front-loaded: the core purpose appears in the first sentence, followed by terse, high-value detail for each id form. Every sentence contributes useful information without redundancy.
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 single-parameter read-only tool with annotations covering safety and idempotence, the description is complete. It covers both id forms, conditional behavior, output shape, and even the fallback for non-text or oversized files. An agent has everything needed to invoke it 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?
Although schema coverage is 100%, the description adds substantial meaning beyond the schema. It explains exactly what each id form yields, including the summary fields and the file-size/type condition. This lets an agent predict output behavior from the parameter value alone.
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 opens with a specific verb and resource: 'Fetch one search result by id.' It then details the two id forms ('site:<site_id>' and 'file:<site_id>:<path>') and what each returns, making the tool's purpose unmistakable. This clearly distinguishes it from search (which returns results) and from other site/file tools.
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 clearly establishes the context for use: after search has returned an id, use fetch to retrieve that specific result. It does not explicitly name alternative tools or exclusions, but the id-returned-by-search framing gives clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the authenticated user's plan, storage used, site count, and plan limits. Useful for checking whether a new site can be created or what storage is remaining.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| plan | Yes | |
| sites_used | Yes | |
| api_key_name | No | |
| custom_domain | No | |
| sites_allowed | Yes | |
| api_key_prefix | No | |
| password_protect | No | |
| storage_used_bytes | Yes | |
| storage_allowed_bytes | Yes | |
| storage_allowed_label | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the data belongs to the authenticated user and enumerates the account dimensions returned, which is useful context beyond what the annotations alone provide.
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?
Two short sentences with the primary return value front-loaded and the actionable use case in the second sentence. No wasted or redundant wording.
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 parameters, a read-only/idempotent annotation set, and an output schema available, the description plus annotations fully cover what an agent needs to select and safely invoke the tool. The use-case sentence resolves the common pre-call decision.
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 has zero parametersorestation; the description need not document inputs. The enumeration of plan, storage, site count, and limits aligns with the expected output and clarifies what account state is being reported.
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 the tool returns account-level data (plan, storage used, site count, plan limits) with a specific verb and resource. The data domain is clearly distinct from the sibling file/site management tools, so an agent can disambiguate without opening 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?
Explicitly ties the tool to a decision point: checking whether a new site can be created or how much storage remains, which is exactly when to call it before create_site. No alternative account-info tool exists among siblings, so not naming one is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a single site, including its live URL, storage size, and current status.
| Name | Required | Description | Default |
|---|---|---|---|
| site_id | Yes | The site's public identifier returned by list_sites or create_site. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| title | No | |
| status | Yes | |
| subdomain | Yes | |
| created_at | Yes | |
| updated_at | Yes | |
| description | No | |
| storage_bytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the description only needs to add context. It adds the kind of details returned (live URL, storage size, status), which is useful, but it doesn't disclose error behavior or what happens for invalid/missing site IDs. No contradiction with 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?
One sentence front-loads the action and resource, then lists the key returned fields. Every word earns its place; there is no redundant restatement of the schema.
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 simple 1-parameter getter with an output schema and strong annotations, the description is adequate: it states what is retrieved and the parameter is fully documented in the schema. It stops short of explicit usage routing, but nothing essential 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 single site_id parameter already has a description explaining its source (list_sites/create_site). The tool description adds no new parameter-level meaning, so 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?
Description uses a specific verb ('Get'), a clear resource ('details of a single site'), and enumerates included fields (live URL, storage size, current status). It is distinct from list_sites, which retrieves multiple sites, and from mutation siblings like update_site/delete_site.
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 intended use is implied by 'single site': call when you need details for one site identified by site_id, not a listing. However, the description doesn't explicitly state when to prefer this over list_sites/search or mention any exclusions, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files on a site. Returns path, size in bytes, content type, and live URL for each file.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | Pagination cursor from a previous list_site_files response. | |
| prefix | No | Filter to files whose path starts with this prefix, e.g. 'assets/'. | |
| site_id | Yes | The site's public identifier returned by list_sites or create_site. |
| Name | Required | Description |
|---|---|---|
| files | Yes | |
| cursor | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it read-only, idempotent, and non-destructive. The description adds behavioral context by specifying the returned fields and implying it returns file metadata, not contents. It does not contradict 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?
Two short sentences that lead with the core action and then the useful result fields. Every sentence earns its place with no filler or redundancy.
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 straightforward read-only listing tool with annotations covering safety and an output schema present, the description covers the essential behavior. It could mention pagination explicitly, but the limit and cursor parameters in the schema partially compensate.
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 input schema already describes site_id, cursor, and prefix, and limit has default/min/max constraints (75% coverage). The description adds no parameter-level detail beyond the schema, so it neither elevates nor harms parameter understanding.
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 ('List files on a site') and enumerates the returned metadata (path, size, content type, live URL). This clearly distinguishes the tool from siblings like read_site_file (single file content) and list_sites.
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 tells what the tool does but gives no guidance on when to choose it over alternatives. It does not mention read_site_file for content retrieval or list_sites for site-level operations, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sites owned by the authenticated user. Returns id, subdomain, live URL, status, and basic metadata for each site.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of sites to return. Default 25. | |
| state | No | Filter by site state. Default is 'active' (live and pending sites). | active |
| cursor | No | Pagination cursor from a previous list_sites response. |
| Name | Required | Description |
|---|---|---|
| sites | Yes | |
| cursor | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: results are scoped to the authenticated user, and the response includes specific site fields. It does not reveal pagination or ordering behavior, but the schema provides cursor details.
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 efficient sentence that front-loads the main purpose and then lists the return fields. No filler or repetition.
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?
The tool is simple, has optional params fully described by the schema, annotations cover side-effect safety, and an output schema exists. The description adds the essential ownership scope and return-field context, making it complete for an agent to invoke 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 100%, so the parameters are already documented (limit, state, cursor). The description does not need to add parameter semantics, and adding none keeps it at the baseline 3.
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 uses a specific verb and resource ('List all sites') and narrows scope to the authenticated user's ownership. The return fields (id, subdomain, live URL, status, metadata) make the tool distinguishable from siblings like get_site and list_site_files.
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 clearly conveys when to use the tool: when enumerating the user's sites. It does not explicitly contrast alternatives like get_site or search, but the 'all sites' framing and listed return fields provide enough context to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the content of a single file on a site. Use mode: 'inline' to get the file content directly (text as UTF-8, binary as base64). Use mode: 'link' to get a short-lived authenticated download URL instead — useful for large files or when passing the URL to another tool. Use mode: 'auto' (default) to inline files under 100 KB and return a link for larger ones. Inline reads are capped at 1 MB.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | inline: return file content directly (UTF-8 or base64; files over 1 MB are refused). link: return a presigned download URL valid for 1 hour. auto: inline if the file is ≤ 100 KB, otherwise return a link. Default is 'auto'. | auto |
| path | Yes | File path relative to site root, e.g. 'index.html' or 'assets/logo.png'. | |
| site_id | Yes | The site's public identifier returned by list_sites or create_site. |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| content | No | |
| encoding | No | |
| expires_at | No | |
| size_bytes | Yes | |
| content_type | Yes | |
| download_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the read-only and non-destructive annotations by disclosing encoding behavior (UTF-8 vs base64), a hard 1 MB inline cap, the short-lived authenticated link semantics, and size-based mode switching. This gives an agent a complete behavioral model for invoking the tool.
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?
One-purpose sentence followed by compact, imperative mode instructions. Every sentence carries information about behavior or thresholds, and there is no filler or unnecessary repetition of schema fields.
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?
Covers all caller-relevant behaviors: modes, size thresholds, link lifetime, and binary/text encoding. With an output schema present and annotations indicating a safe read-only, idempotent operation, nothing critical is missing for an agent to select and invoke this 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?
The input schema already has 100% parameter coverage, including full descriptions of the mode enum, so the baseline is high. The description adds useful context such as the large-file rationale and the 'passing the URL to another tool' use case, which helps an agent pick the right mode.
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 the operation precisely: 'Read the content of a single file on a site.' The verb, resource, and single-file scope clearly differentiate it from sibling tools like list_site_files, write_site_files, and delete_site_files. The mode options also make its behavior 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?
Provides explicit guidance for choosing among 'inline', 'link', and 'auto', including the 100 KB auto threshold and the large-file/pass-to-another-tool rationale for link. It does not explicitly name sibling tools as alternatives, but the single-file read scope and detailed mode guidance make the intended context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace ALL files on a site with a new set. Any file not included in this call is deleted. Use when rebuilding a site from scratch. Limit: 200 files per call, 1 MB per file.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | The complete new file set for the site. | |
| site_id | Yes | The site's public identifier returned by list_sites or create_site. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| written | Yes | |
| warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already declare destructiveHint=true, the description discloses precisely what gets destroyed: any file not included in the call is deleted. This is exactly the sort of behavioral context annotations cannot convey. It also adds hard operational limits (200 files per call, 1 MB per file) that describe real-world constraints on invocation. No contradiction with 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?
Three sentences, zero filler. The most critical fact (full replacement with deletion of unlisted files) is front-loaded, followed by usage guidance and limits. Every sentence earns its place.
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 operation with an output schema, annotations, 100% parameter coverage, and an explicit usage note, this is nearly complete. The only gap is that it never names the sibling write_site_files as the non-destructive alternative, which would help an agent deciding between the two tools.
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 schema documents both parameters well. The description adds genuine value beyond it: the 'notes' parameter's semantics as a complete replacement set (anything absent is deleted) reinforces and extends the schema's 'complete new file set' wording, and the 1 MB per-file limit is a constraint not present in 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 states a specific verb and resource ('Replace ALL files on a site with a new set') and immediately clarifies the tool's distinguishing destructive scope — unlisted files are deleted. This cleanly separates it from the sibling write_site_files and delete_site_files, so an agent can identify the right tool 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?
The description gives an explicit when-to-use directive ('Use when rebuilding a site from scratch'), which clearly scopes the tool's appropriate context. It does not explicitly name the alternative (write_site_files) for non-destructive updates, but the context provided is unambiguous enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reserve presigned PUT URLs for uploading one or more large or binary files directly to storage — bypassing the 1 MB inline limit. Omit site_id to create a new pending site atomically (supply subdomain/title for the new site). Provide site_id to add or replace files on an existing site. The caller must PUT each file to its returned upload_url, then call confirm_upload once with the batch upload_id.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Only used with site_id. merge = add/overwrite the specified files while keeping all other site files. replace = replace the entire site with only these files. Default is 'merge'. A new site (no site_id) always publishes exactly this batch. | merge |
| files | Yes | One or more files to upload. All files in this call are confirmed together as a single atomic batch. | |
| title | No | Display name for the new site. Only used when site_id is omitted. Optional. | |
| site_id | No | The site's public identifier. Omit when creating a new site — the pending site and batch are created in one operation. | |
| subdomain | No | Requested subdomain for the new site. Only used when site_id is omitted. Optional — Upfling assigns one if omitted. |
| Name | Required | Description |
|---|---|---|
| slots | Yes | |
| site_id | No | |
| upload_id | Yes | |
| expires_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the full burden of behavioral disclosure. It reveals the multi-step nature (PUT each file, then confirm_upload), the atomic batch semantics for new sites, the mode-dependent behavior (merge vs replace), and the fact that a new site is created as 'pending.' This goes well beyond the annotations and gives an agent a realistic model of the operation's side effects.
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 sentences, no filler. The core purpose is front-loaded, the two usage branches are clearly separated, and the required follow-up action is stated at the end. Every sentence contributes essential information.
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 the tool's complexity (multi-step upload, new vs existing site, merge/replace modes), the description covers the full workflow, the atomicity guarantee, and the dependency on confirm_upload. An output schema exists, so return values need not be described. No critical operational detail 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%, so the baseline is 3. The description adds value by explaining the conditional semantics of site_id ('Omit when creating a new site... Provide to add or replace files'), clarifying that subdomain/title are only used for new sites, and noting that a new site always publishes exactly the batch. These relationships are not fully captured in the schema's per-field descriptions.
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 opens with a specific verb and resource: 'Reserve presigned PUT URLs for uploading one or more large or binary files directly to storage.' It clearly distinguishes the tool from siblings by mentioning the 1 MB inline limit bypass and the follow-up confirm_upload step, so an agent can tell it apart from write_site_files or replace_site_files without inspecting 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?
The description gives clear context for when to use the tool: for large/binary files exceeding the inline limit, and it explains the two distinct usage branches (omit site_id for new site, provide site_id for existing site). It does not explicitly name alternative tools for small files, but the 'bypassing the 1 MB inline limit' phrasing implies the alternative, and the workflow with confirm_upload is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the authenticated user's own sites by subdomain, custom domain, title, description, and file path (case-insensitive substring; not file contents). Returns up to 20 results as {id, title, url}: ids are 'site:' or 'file::', and url is the live address. Pass an empty query to list the user's sites. Use fetch with a returned id to read it.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Text to look for in the user's own sites: subdomain, custom domain, title, description, or file path. An empty string lists the user's sites. |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description discloses useful behavior: case-insensitive substring matching, exclusion of file contents, a 20-result cap, the exact id format ('site:<site_id>' or 'file:<site_id>:<path>'), and the fact that url is the live address. This gives an agent a clear model of what the call will do.
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 four tightly written sentences with no filler. The most important constraints are front-loaded, and every sentence contributes either scope, result format, or a follow-up instruction.
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 single-parameter read-only search tool, the description covers everything needed to call it correctly: searched fields, exclusions, result limits, id semantics, empty-query behavior, and the recommended next action. The output schema exists for detailed return fields, so the description is appropriately complete.
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 schema already documents the query parameter with 100% coverage, establishing the baseline at 3. The description adds meaningful semantic detail beyond the schema: matching is case-insensitive, operates on substrings, excludes file contents, and an empty string lists the user's sites.
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 states a specific action and resource: searching the authenticated user's own sites. It enumerates the exact searchable fields (subdomain, custom domain, title, description, file path) and explicitly excludes file contents, making it clearly distinct from siblings like list_sites and fetch.
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 clear context for when to use the tool: searching a user's own sites by metadata or file path, with an explicit empty-query mode for listing sites. It also directs the agent to use fetch with a returned id to read the result. It does not cross-reference list_sites as an alternative, but the core usage guidance is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a site's metadata: title, subdomain (changes the live URL), description, password protection, or homepage file. Omit any field to leave it unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | New display name for the site. | |
| site_id | Yes | The site's public identifier returned by list_sites or create_site. | |
| homepage | No | Path to the homepage file, e.g. 'index.html'. Pass null to use Upfling's default. | |
| password | No | Set a password (Lite+ plan required). Pass null to remove password protection. | |
| subdomain | No | New subdomain. Changes the live URL — existing links will break. | |
| description | No | Short description. Pass null to clear. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| url | Yes | |
| title | No | |
| status | Yes | |
| subdomain | Yes | |
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it warns that changing the subdomain 'changes the live URL — existing links will break' and notes that password protection requires a 'Lite+ plan'. These are side effects and prerequisites not captured in annotations. Annotations already declare idempotentHint=true and destructiveHint=false, so the description does not contradict them and provides supplementary detail.
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, efficient sentence that front-loads the action and lists the mutable fields. Every clause adds value: the field list informs what can be updated, and the omission note clarifies behavior. There is zero redundancy or 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 the output schema exists and annotations cover idempotency and non-destructiveness, the description covers the key context: side effects (subdomain change) and a prerequisite (Lite+ plan). It does not mention error handling or the behavior for invalid site_ids, but these are likely standard and not essential for correct invocation. The description is sufficiently complete for an agent to use it 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 description coverage is 100%, so every parameter has a description in the schema. The description adds a general note about omitting fields to leave them unchanged, which clarifies the update semantics but does not add per-parameter detail beyond the schema. This is adequate but not exceptional; 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?
The description clearly states the tool's purpose: 'Update a site's metadata' and enumerates the specific fields (title, subdomain, description, password protection, homepage file). This differentiates it from sibling tools like create_site and delete_site. The verb-resource pairing is explicit and 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?
The description implies usage (updating an existing site) but does not explicitly state when to choose this tool over alternatives like create_site or delete_site. It provides a useful operational note ('Omit any field to leave it unchanged') but lacks explicit exclusions or comparisons to siblings. The context is clear enough for an agent to infer, but it stops short of explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add or overwrite specific files on an existing site without touching other files. Use this to update an existing page, add a new asset, or fix a typo. Limit: 200 files per call, 1 MB per file.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | Files to write. Each entry is a path + UTF-8 content string. | |
| site_id | Yes | The site's public identifier returned by list_sites or create_site. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| written | Yes | |
| warnings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the annotations: 'without touching other files' clarifies the mutation scope, and the file-count/size limits communicate operational constraints. It is consistent with readOnlyHint=false and idempotentHint=true, though it does not detail error behavior or permissions. No annotation contradiction detected.
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 concise sentences deliver the core operation, use cases, and limits in order of importance. There is no filler or redundant repetition of the schema.
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?
An output schema exists, so return values do not need explanation. The description covers scope, use cases, and important limits. It could be slightly stronger by explicitly contrasting with replace_site_files or delete_site_files, but the current description is sufficient for a 2-parameter tool with well-covered schema.
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%, so parameters (site_id, files, path, content) are already well documented. The description adds little beyond the 1 MB per-file limit; it does not substantially compensate for anything missing in the schema, so the baseline score of 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?
The description states a specific operation—'Add or overwrite specific files'—on an existing site)Skip it is narrowly scoped by 'without touching other files,' which distinguishes it from broader sibling tools like replace_site_files or delete_site_files. The examples (update page, add asset, fix typo) further clarify the intended purpose.
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 explicitly provides use cases: updating an existing page, adding a new asset, or fixing a typo. It gives clear context for when to use the tool, though it does not name alternative sibling tools or state 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
confirm_uploadcreate_sitedelete_sitedelete_site_filesfetchget_account_infoget_sitelist_site_fileslist_sitesread_site_filereplace_site_filesrequest_uploadsearchupdate_sitewrite_site_files
Add one secure layer between your agents and this server.