buildium-mcp

Buildium Download File

buildium_download_file

Destructive

Download any Buildium file to your machine using its ID, bypassing expiring URLs. Saves to your configured download folder with optional rename and overwrite settings.

Instructions

Download a Buildium file to this machine, handling both steps.

Buildium issues a download URL that expires after five minutes and serves the bytes from separate storage, so this cannot be done with buildium_get.

Files are written only inside the download folder — ~/Downloads/Buildium unless BUILDIUM_DOWNLOAD_DIR moves it; buildium_health reports where. An existing file is never replaced unless overwrite is true.

Note this is refused when the server runs in production-readonly mode: Buildium models a download request as a POST, and that mode blocks every POST at the transport layer without exception. Reading file metadata via GET /v1/files/{id} still works.

Input Schema

TableJSON Schema

Name	Required	Description
`file_id`	Yes	The file's ID, from GET /v1/files.
`save_to`	No	A file name, or a path inside the download folder; relative paths are taken relative to it. Omit to save as buildium-file-<id> with an extension from the content type.
`overwrite`	No	Replace a file that already exists at that name.
`download_path`	No	For a file belonging to a bill, check or task history, that resource's own download path, e.g. "/v1/bills/123/files/456/downloadrequest". Only Buildium's seven download endpoints are accepted.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.2.1Sep 24, 2026

addedInput schema / properties / download_path / description

Added value: +"For a file belonging to a bill, check or task history, that resource's own download path, e.g. \"/v1/bills/123/files/456/downloadrequest\". Only Buildium's seven download endpoints are accepted."

addedInput schema / properties / file_id / description
```
Added value: +"The file's ID, from GET /v1/files."
```

addedInput schema / properties / overwrite / description

Added value: +"Replace a file that already exists at that name."

addedInput schema / properties / save_to / description

Added value: +"A file name, or a path inside the download folder; relative paths are taken relative to it. Omit to save as buildium-file-<id> with an extension from the content type."

Changed5 schema fields changedv0.2.0Sep 23, 2026

addedInput schema / properties / overwrite

Added value: +{
+  "default": false,
+  "type": "boolean"
+}

addedInput schema / properties / save_to / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / save_to / default
```
Added value: +null
```
removedInput schema / properties / save_to / type
```
Removed value: -"string"
```

changedInput schema / required

Previous value: -[
-  "file_id",
-  "save_to"
-]New value: +[
+  "file_id"
+]

First observedv0.1.0Sep 17, 2026

TDQS

A5/5.0

Behavior5/5

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

Goes well beyond the annotations: explains the two-step download flow, file location (~/Downloads/Buildium), overwrite semantics tied to destructiveHint=true, and the transport-layer POST block. No contradiction with annotations; it adds meaningful behavioral context the annotations cannot convey.

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?

Every sentence earns its place. The main purpose is front-loaded, then constraints and exceptions are layered logically. It is detailed but not redundant; no filler.

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

Completeness5/5

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

For a tool with a two-step flow, special mode restrictions, and an output schema, the description covers all essentials: how the flow works, where files go, overwrite behavior, and failure modes. The presence of an output schema relieves it from describing return values, and 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.

Parameters5/5

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

Although schema coverage is 100%, the description enriches each parameter: save_to's default naming and relative path handling, download_path's constraint to seven endpoints, and overwrite's default false. This is genuine added meaning beyond the schema.

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 opens with a clear verb and resource: 'Download a Buildium file to this machine,' and immediately differentiates from buildium_get by explaining why that tool cannot be used (expiring URL, separate storage). This unambiguously identifies the tool's purpose and distinguishes it from a close sibling.

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

Usage Guidelines5/5

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

Explicitly states that buildium_get cannot handle this task and why, giving the agent a clear routing rule. It also discloses the production-readonly mode refusal and notes that metadata reading via GET still works, providing concrete when-to-use and when-not-to-use guidance.

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