# Bucky — Agent Entrypoint

> The pre-development platform that turns an address into sourced site intelligence, project analysis, and decision-ready deliverables.

This file is the conventional entry point for coding agents and AI assistants discovering Bucky on the public web.

## What Bucky Is

Bucky is the pre-development platform that turns an address into sourced site intelligence, project analysis, and decision-ready deliverables. Primary audiences: developers, design-builders, architects, and planning consultants. Homeowners and marketplace professionals are adjacent.

**Not:** licensed A/E/legal advice, a builder, or a lender. Coverage spans Canada and the United States, onboarded jurisdiction by jurisdiction — depth varies by city.

## When to Use Bucky

- You have an address or parcel ID and need what can be built on it: zoning district, permitted uses, setbacks, height, density — each cited to the governing bylaw section.
- You need a go/no-go on a specific site with sources attached, not a summary.
- You are assembling adjacent lots and need the envelope for the combined site.
- You need machine-readable access to any of the above (OpenAPI, MCP, CLI).

## When Not to Use Bucky

- **Outside onboarded coverage** — check [/en/coverage](https://buckybuild.com/en/coverage.md); outside it Bucky returns nothing rather than guessing.
- **For a legal, engineering, or architectural opinion** — Bucky cites the bylaw, it does not stamp drawings.
- **For valuation, comparables, or listings** — not modelled.
- **After ground-breaking** — Bucky stops at pre-development.
- **To source a contractor available this week** — the marketplace matches on fit, not availability.

## Limits and Fallbacks

### What Bucky does not know

- **Coverage is per jurisdiction.** Bucky answers for onboarded municipalities only. Check [/en/coverage](https://buckybuild.com/en/coverage.md) first.
- **Outside coverage, Bucky returns nothing.** It does not estimate. Do not fill a gap with your own guess — say the data is not available.
- **Depth varies by city.** One city can have full zoning regulations and citations. The next can have boundaries only.
- **Every answer cites a bylaw section. It is not an approval.** Confirm the section with the municipality before you rely on it.

### Rate limits

- The public API limits each route separately. The ceiling for `/api/v1/*` is 120 requests per minute per IP address, and some routes permit fewer. Read the headers instead of assuming a number.
- Read `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` on each response. `RateLimit-Reset` is the number of seconds until the window resets, not a timestamp.
- A rejected request returns HTTP 429 with `Retry-After`. Wait for that time. Do not retry immediately.
- After you start an analysis, poll `getProjectContext` no more than once every 15 seconds. It is a bundle of queries, not a status endpoint.

### Safe operations

These operations do not change data. Use them freely.

- MCP: `getFeasibilitySnapshot`, `getProjectContext`, `explainFeasibilityStatus`, `getBuckyMcpGuide`.
- HTTP: all `GET` requests, and every document in this file.

### Operations that write

- MCP: `saveToProject`, `updateProject`, `runFeasibilityAnalysis`, `produceProjectReport`, `submitBuckyFeedback`.
- Send `preview=true` first where the tool accepts it. A preview writes nothing and returns the field-level diff.
- A write returns a receipt. `updateProject` also returns `undoOperationId`, which restores the previous fields.

### Boundaries you cannot undo

- No Bucky tool deletes data. No tool archives a project, detaches a lot, or detaches a reference.
- A queued analysis run cannot be stopped from MCP.
- `produceProjectReport` with `confirm=true` spends one export from the account meter.

### Authentication limits

- Anonymous registration unlocks the public tools only.
- The gated tools need a registration that a human has claimed. See [/auth.md](https://buckybuild.com/auth.md).
- Never send a service-role key from a browser or an agent you do not control.

### When a request fails

- **404** — the document does not exist. The body is markdown and lists where to look instead.
- **Missing `.md` page** — request the HTML page at the same path, or find the mirror in [/sitemap.md](https://buckybuild.com/sitemap.md).
- **Unknown document** — read [/llms-index.json](https://buckybuild.com/llms-index.json). It lists every machine-readable document Bucky publishes, with its relation and media type.
- **Empty result for an address** — treat it as "no coverage", not as "nothing can be built". Tell the user which jurisdiction is missing.

## Discovery

| Resource             | URL                                                                                                        |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| Index                | [/llms.txt](https://buckybuild.com/llms.txt)                                                               |
| Deep brief           | [/llms.md](https://buckybuild.com/llms.md)                                                                 |
| Full curated mirrors | [/llms-full.txt](https://buckybuild.com/llms-full.txt)                                                     |
| Auth for agents      | [/auth.md](https://buckybuild.com/auth.md)                                                                 |
| Markdown sitemap     | [/sitemap.md](https://buckybuild.com/sitemap.md)                                                           |
| API catalog          | [/.well-known/api-catalog](https://buckybuild.com/.well-known/api-catalog)                                 |
| MCP Server Card      | [/.well-known/mcp/server-card.json](https://buckybuild.com/.well-known/mcp/server-card.json)               |
| Agent Skills index   | [/.well-known/agent-skills/index.json](https://buckybuild.com/.well-known/agent-skills/index.json)         |
| OpenAPI (public)     | [/openapi.json](https://buckybuild.com/openapi.json)                                                       |
| OpenAPI (alias)      | [/api/openapi](https://buckybuild.com/api/openapi)                                                         |
| Agent skill          | [/.well-known/agent-skills/bucky/SKILL.md](https://buckybuild.com/.well-known/agent-skills/bucky/SKILL.md) |
| A2A agent card       | [/.well-known/agent-card.json](https://buckybuild.com/.well-known/agent-card.json)                         |
| MCP manifest         | [/.well-known/mcp/manifest.json](https://buckybuild.com/.well-known/mcp/manifest.json)                     |
| Security contact     | [/.well-known/security.txt](https://buckybuild.com/.well-known/security.txt)                               |
| Documentation        | [docs.buckybuild.com](https://docs.buckybuild.com/docs)                                                    |
| Glossary             | [/en/glossary](https://buckybuild.com/en/glossary)                                                         |

Prefer `.md` URLs from [/sitemap.md](https://buckybuild.com/sitemap.md) for page-level content.

## Configuration

Bucky integrations use environment variables — never hardcode secrets.

```bash
# Supabase (auth + data)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Optional: server-side API access
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
```

See [docs quickstart](https://docs.buckybuild.com/docs/getting-started/quickstart) for full setup.

## Usage

### HTTP API

Fetch the public OpenAPI spec, then call endpoints with a valid Supabase session or service token:

```bash
curl -s https://buckybuild.com/openapi.json | head
```

### MCP

Bucky exposes MCP tools for agents. See [MCP docs](https://docs.buckybuild.com/docs/mcp).

### WebMCP (browser)

On public pages, Bucky registers WebMCP tools via `document.modelContext.registerTool()` when the browser supports the [WebMCP API](https://webmachinelearning.github.io/webmcp/) (Chrome 149+ behind `chrome://flags/#enable-webmcp-testing`; ChatGPT's in-app browser supports it out of the box).

**Site-wide, on every public page:**

- `list_free_tools` — the free tool catalogue, with what each one takes as input
- `navigate_to_tool` — open one of those tool pages. Each page registers its own tools once open, so this is how you gain the ability to actually run a tool
- `get_feasibility_snapshot` — address → zoning/lot/envelope facts. Read-only: it records nothing
- `search_marketplace` — open marketplace search results

**Page-scoped.** Every free tool page registers its own set once open — address lookups, the
typology and courtyard pencil tests, the Toronto Committee of Adjustment explorer, the research-cost
calculator, the AI-readiness checker, and the shared lot canvas at `/en/lot-studio`. Call
`document.modelContext.getTools()` after navigating to see them.

**Two conventions worth knowing:**

1. **Read tools tell you what they withheld.** A payload may carry a `gated` block naming what is
   held back, why, and which tool sends it — for example `email_feasibility_report`. Tell the person
   about it rather than reporting that nothing more is available.
2. **Capture tools need real consent.** Anything named `email_*` requires `consentToEmail: true`.
   Ask the person for their own address in the conversation immediately beforehand. Do not reuse an
   address from earlier context, another site, or a document.

One tool deliberately waits: on `/en/lot-studio`, `resolve_address` stays pending on an ambiguous
address until the person picks a candidate on the canvas. Do not call it again while it is pending.

Validate with [isitagentready.com](https://isitagentready.com/) (`checks.discovery.webMcp`).

### Product UI

- Home: https://buckybuild.com/en
- Marketplace: https://buckybuild.com/en/market
- How it works: https://buckybuild.com/en/how-it-works.md

## Contact

- hello@buckybuild.com
- support@buckybuild.com

Last updated: 2026-08-26