The external tool surface

This is the surface an external client sees. It is not the tool server the cards use: that one serves twenty-six finance tools over the loopback address, gated by capability. This one serves seven desk gestures over standard input and output.

Seven, and not one more. Each matches something the operator could do in the application. A wider surface would hand a client powers the screen itself does not have — and every tool added is a tool a third party can call.

#Three rules the surface follows

• No tool takes a path. A client is a third party; what it can name has to be bounded, and a test holds that.
• An artifact returns its summary, its size, its digest and a resource URI — never its bytes. A workbook inlined into a tool result would drown the client’s context for nothing, since it already has the address.
• A prompt is chosen by the user, never by the model 4. Each one states what it refuses to invent: without that sentence, a desk fills a missing figure with an estimate that reads like a reading.

#Starting a desk returns immediately

A desk runs for minutes, not seconds. The tool that opens one returns a mission identifier straight away; the client then polls the status and reads the result when it is done. A tool that blocked for the length of a mission would time out in every client that exists.

LimitThe status is queued until the window says it has taken the mission, and started only after. In 0.0.24 nothing sent that acknowledgement and every mission stayed queued; the window sends it now, at the moment it takes the request rather than at the end of the first turn. A mission that is still queued means the window is closed, starting, or busy — the tool would rather say so than report a start that did not happen.