MCP tools

Everything is on one endpoint: https://api.uely.ch/mcp.

Public: no token

These answer for anyone. They read published data or start a signup; none of them touches a private workspace.

Tool	What it does
search_listings	Search the public marketplace
get_listing	One published listing
get_farm_profile	A farm’s public page
search_handbook	Full-text search of this handbook: title, description and page text
get_handbook_page	One handbook page
get_signup_info	Plans and prices, and the rule about never asking for a card
start_signup	Open a Stripe Checkout for someone with no account
get_signup_session	Poll a signup: statuses only

Scoped: token plus a paid plan

Tool	Scope
ask	ask
continue_ask	ask
research	research
get_research_status	research
upload_training, get_training_status, get_source_url	training.write

Writes inside ask additionally need workspace.write.

There is no tool for reading one kind of thing

There used to be fifteen: list_documents, get_contact, place_at and the rest, one pair per kind of record. They are gone, and so are the seven scopes that opened them.

Ask instead. ask is the same agent the person uses in the app, with the same tools: it reads their documents, places, animals, work, correspondence and the knowledge base, and decides for itself what to look at. “Welche Kontakte habe ich in Bern” is a better question than three calls to a list tool, and it is the only kind this endpoint now takes.

If you were calling those tools, the migration is to ask for what you wanted. If you need rows rather than prose (a table to render, say), say so in the question.

Reach

Every scoped tool acts as the person who consented. There is no parameter that selects a different person. ask sees that person’s own area and every team they are an active member of. There is no separate team grant on the token.

ask

ask runs the same service as POST /chat/ask and the same agent as the app’s own chat, minus the parts that need a screen: no A2UI forms, because there is nobody to fill one in.

Conversations. The reply carries a conversation_id. Pass it back to continue that thread; omit it to start a new one. An agent conversation is separate from the person’s own chat window in the app and never reads it.

Writes. With the workspace.write scope the agent can change things, but never silently. The reply comes back with status = needs_approval and a pending list of the actions it proposes, and nothing happens until you send a decision to continue_ask. Put that list in front of your person in their own words and send what they choose. Without the scope the run is read-only and never pauses.

It is charged per call, and an MCP tools/call carries no idempotency key: a retry is a second question and a second charge. If you need retries to be free, use the REST route with an Idempotency-Key. That route stays read-only even with workspace.write: there is nowhere to answer a pause over REST yet.

Each ask also lands in the person’s chat history, marked as coming from your client. They can see what you asked.

continue_ask

Takes the message_id from a paused reply and one entry per tool_call_id in its pending list: {"tool_call_id": "...", "approved": true}, or false with an optional reason the agent is told. You may approve some and refuse others.

Calling twice for the same pause is refused rather than done twice.

research

A written report answering from Uely’s agricultural knowledge base: research findings, official guidance and cantonal practice for Swiss agriculture, in German, French and Italian, including material that general web search does not reach because it sits in PDFs on cantonal sites rather than on the open web.

It reads no workspace. The run’s toolset contains no verb that could, and the run carries no workspace identifier for one to resolve against. Use ask for questions about a farm’s own data, and research for questions about the subject matter.

Ask in any language; the report comes back in German with its sources. A specific question earns a better report than a topic. Name the crop, animal, canton or regulation.

Returns a job_id, not a report. A report reads a large corpus and takes one to several minutes; poll get_research_status with that id until status is succeeded.

Charged per call like ask, and an MCP tools/call carries no idempotency key, so a retry is a second report and a second charge. Use POST /research with an Idempotency-Key if you need retries to be free.

get_research_status

Takes the job_id that research returned. Answers queued, running, succeeded or failed; a succeeded job carries the report and its citations, a failed one carries error.

Polling is free; only starting a report is charged. Leave a moment between calls.

upload_training

Takes file_name and content, returns 202 with an upload_id and a poll path. Ingest is asynchronous; poll get_training_status or GET /training/{id}.

Text only, and capped. Send the extracted text, not a PDF.

Uploads are stamped with your client_id, and the person sees in their sources list that a program added them.

get_source_url

The way back out. A source goes in as a file and cannot come back through a tool result, so this returns a presigned URL valid for fifteen minutes. Fetch it over plain HTTP. Paginated sources also carry preview_url and page_urls.

You can only link to sources the connected workspace can already see.

Errors

A tool that fails for a reason you can act on says so. Anything else is a generic message plus a server-side log. Production never returns internals. A tool name that does not exist, and one that exists but is unclassified, are both refused: the classification is default-deny, so a new tool is unreachable rather than accidentally public.