buildium-mcp

Buildium Upload File

buildium_upload_file

Destructive

Upload a local file to Buildium by handling the two-step presigned URL flow, eliminating failed PUT attempts when using the API directly.

Instructions

Upload a local file to Buildium, handling both steps of its upload flow.

Bytes do not travel through the Buildium API. Buildium issues a short-lived AWS presigned PUT URL, and the file is sent there directly. Doing that by hand with buildium_call_endpoint does not work — it would post the metadata and hand you a URL it cannot then PUT to. Use this instead.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`title`	Yes	The file's title in Buildium. In 'fixtures' write mode it must start with the fixture prefix (see buildium_health).
`entity_id`	No	The ID of that record.
`file_path`	Yes	Path to the file on this machine. Hidden files, *.env files and this server's own configuration are refused.
`category_id`	Yes	File category, from GET /v1/files/categories. Buildium rejects the upload without a real one.
`description`	No	Optional description stored with the file.
`entity_type`	No	What the file is attached to: Rental, Lease, Tenant, Vendor, Association, RentalOwner, RentalUnit, and so on.	Rental
`upload_path`	No	For a file belonging to a bill, check or task history, that resource's own uploads path, e.g. "/v1/bills/123/files/uploads". Only Buildium's seven upload endpoints are accepted.	/v1/files/uploads

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.2.1Sep 24, 2026

addedInput schema / properties / category_id / description

Added value: +"File category, from GET /v1/files/categories. Buildium rejects the upload without a real one."

addedInput schema / properties / description / description

Added value: +"Optional description stored with the file."

addedInput schema / properties / entity_id / description
```
Added value: +"The ID of that record."
```

addedInput schema / properties / entity_type / description

Added value: +"What the file is attached to: Rental, Lease, Tenant, Vendor, Association, RentalOwner, RentalUnit, and so on."

addedInput schema / properties / file_path / description

Added value: +"Path to the file on this machine. Hidden files, *.env files and this server's own configuration are refused."

addedInput schema / properties / title / description

Added value: +"The file's title in Buildium. In 'fixtures' write mode it must start with the fixture prefix (see buildium_health)."

addedInput schema / properties / upload_path / description

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

First observedv0.1.0Sep 17, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Adds meaningful behavioral context beyond the annotations by disclosing that bytes do not travel through the Buildium API and that the upload uses a short-lived AWS presigned PUT URL. It also warns about the generic endpoint's limitation, which is valuable non-obvious behavior.

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?

Three compact sentences deliver the purpose, the underlying mechanism, and the routing guidance away from buildium_call_endpoint. There is no filler or redundant repetition of schema information.

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?

Given the full schema coverage, the presence of an output schema, and annotations covering safety hints, the description adds the critical non-obvious context about the presigned URL flow. An agent has everything needed to invoke the tool correctly and avoid the common alternative mistake.

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?

All seven parameters already have full descriptions in the input schema, so the description does not need to repeat them. The description adds no parameter-specific details, but the schema fully covers parameter semantics, so the baseline of 3 is appropriate.

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?

States the specific action 'Upload a local file to Buildium' and highlights that it handles both steps of the upload flow. It also distinguishes itself from buildium_call_endpoint by explaining why that alternative cannot complete the upload.

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 names buildium_call_endpoint as the wrong alternative and explains exactly why it fails: it posts metadata and hands you a presigned URL it cannot PUT to. The description then directs the agent to use this tool instead, leaving no ambiguity.

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