Procedures and Tools

A resource tree describes what an application offers: routes, the methods on them, what each accepts and returns, and who may call it. HTTP is one way to present that description. The gateway can present the same description in other forms, for callers that do not speak in resources.

Nothing is declared twice. The routes are the single source, and the other forms are views of them.

§Procedures

Some callers prefer procedures to resources: a single endpoint, a method name, parameters, a result. The gateway can serve every route as a procedure, using JSON-RPC.

A procedure’s name is derived from the route and the method:

The name is not chosen; it is the address written another way. Parameters carry what a request would carry: route variables, the query, and the body.

A procedure call is the same call the route would make. It passes through the same directives, is authorized as the same identity, and reaches the same operation. A procedure for a GET may only read, exactly as the GET may.

§Tools

A language model that acts on a user’s behalf calls tools: named functions with described inputs. The gateway can serve the application’s routes as tools through the Model Context Protocol.

Unlike procedures, tools are selected. A method becomes a tool where it says so:

/:id:
  GET:
    mcp:tool: true
    help:method:
      title: An order
      description: The status and total of one order.
    endpoint: observe

The selection matters because a tool list is read by a model. A model chooses among tools by their descriptions, so a small set of well-described tools serves it better than every route the application has.

What a tool accepts is the operation’s input contract. What it returns is the route’s output. Whether it is presented as read-only follows from what the route may do, so a client that lets a model call read-only tools freely is told the truth about each one.

§The same rules

A model calling a tool is a caller like any other. It holds a credential for an identity, typically obtained with the user’s consent as described in Identity and Access, and each call is authorized against the route’s directives.

This is the reason to expose tools from the resource tree instead of building a separate integration. An application does not acquire a second, differently secured surface. A model can do what the user it acts for can do, restricted further to the scopes the user granted, through the same operations as every other client.

§Describing what is offered

For any of these forms to be usable, a caller has to learn what exists. The gateway answers that from the declarations:

• a resource can be asked what methods it has and what each accepts and returns;
• the application can be asked for every route the asking identity may call.

Titles and descriptions are declared on the tree beside the routes they describe. They are read by people browsing the application’s interface and by models choosing tools, and they travel with the route into every form it is presented in.

§Why this is possible

Each of these forms needs the same facts: a name, a contract for input and output, an access rule, and whether the call can change anything. In Toa those facts are declared, not embedded in handler code, so they can be read as well as executed.

This is a recurring result of product–platform separation. What an application declares, the platform can serve in ways the application’s authors did not have to anticipate.