Subsystem

HTTP API: discovery

The 3 operations tagged discovery, each with its parameters, its body and what it answers.

A guide written for an agent

GET /v1/docs/agent

Serve §13.3's guide. The text is :func:guide_text, so a client can reach it too.

Responses

Worked calls, in the order an agent needs them

GET /v1/docs/examples

Serve the worked calls. The text is :func:examples_text, so a client can reach it.

Responses

What does this installation call things?

GET /v1/meta

Report this installation's vocabulary, limits and grammars.

Refuses a query parameter it does not accept, which no other single-entity read does. The rule api/query.py states is that a listing refuses because an ignored parameter costs payload, and a single-entity read is exempt because it wastes nothing. This endpoint breaks that criterion: a discarded parameter here does not return too much, it returns a different answer that looks like a true one.

?workspace=projects — the spelling every MCP tool uses — was dropped, and the reply was 200 with workspace: null and empty vocabulary maps, which is exactly what a fresh instance with no custom vocabulary would say. An agent read it that way, concluded the status keys were unavailable, derived them instead from the statuses in use, decided there was no way to close an item as a duplicate, and deleted a task rather than cancelling it. cancelled had been there the whole time.

So the criterion is not "collection or entity", it is whether ignoring the parameter changes the answer or only its size. This is the one read whose entire answer is chosen by a query parameter, with no path segment naming the subject and no ambiguity refusal underneath it to catch the mistake.

Parameters

Responses