Specification · Markdown source · Edit on GitHub · CC0 1.0

VRP Node Tool Binding — Specification v0.1

Status: Public draft — proposal for discussion (tracks issue #156). Additive by construction: Core v0.1 defines documents and verification rules, not runtime tools, and that does not change here. This document binds the one name and the one argument shape a node uses when it chooses to expose its signed offer as a tool. A node that exposes no tool surface is unaffected, and nothing here changes what a v0.1 verifier MUST do today.

Published: 2026-10-21

Repository: https://github.com/vacationrentalprotocol/vrp-spec

Builds on: Core VRP v0.1 (§2 discovery document, §3 JWKS, §4 endpoint parameters, §5 signed offer, §5.1 direct_booking_url, §6–§9 freshness, safe-to-quote, fail-closed, three-state verification), Well-Known URI v0.1, MCP composition profile (the tool name in the transport assertion, snake_case argument keys).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.

1. Scope

A VRP node publishes its facts as documents on its own domain (Core v0.1). Agents increasingly reach a site through tool-calling surfaces as well: a Model Context Protocol (MCP) server, an Agent2Agent (A2A) agent card, or a tool a page registers in the browser through WebMCP. Each surface has its own way to name a capability. Without a binding, the same node would call the same capability by three names, and an agent that learned one would not recognise the other two. Left to implementers, the name becomes an operator's instead of the protocol's.

This document binds, for every tool surface a node exposes:

Out of scope: how an agent finds a node (StayIntent discovery, open-web search), search or ranking of any kind, payment, and any tool other than the one bound here. A node MAY expose other tools under names of its own choosing; this document does not name them.

2. Terms

3. The capability name

The capability that returns the node's signed verified stay offer is named:

get_verified_stay_offer
SurfaceField bound to the nameWhere it is defined
MCPname of the tool in the tools/list result, the name a tools/call request carriesModel Context Protocol, Tools
A2Aid of the skill in the agent card's skills[]Agent2Agent Protocol, AgentCard and AgentSkill
WebMCPname passed to registerTool()Web Model Context API (W3C Web Machine Learning Community Group draft)

Why no prefix. The name identifies a protocol capability, not an operator. The node's identity is its domain, and every surface already carries that domain: the MCP endpoint URL, the agent card's endpoint URL and the host that served the card, the page's origin. Putting the domain or the operator into the name would say the same thing twice and would make every node's capability a different word. Clients tell same-named tools apart by the server they came from: MCP leaves that disambiguation to the client, and WebMCP requires a name to be unique within one document, not across the web.

4. Arguments

The capability takes the parameters of the verified stay offer endpoint (Core v0.1 §4), with the same names and formats:

ArgumentTypeRequirement
check_instring, YYYY-MM-DDREQUIRED
check_outstring, YYYY-MM-DDREQUIRED
guestsinteger, at least 1REQUIRED

5. Result

6. Origin binding

The tool surface and the offer are on the same domain:

7. Who may use the name

8. Verification is the agent's

Nothing on a tool surface is a trust signal: not the name, not the description, not the annotations, not a signature on the card, not the transport. An agent:

  1. MUST verify the returned envelope's signature against the JWKS the node's discovery document names (Core §3, §9), exactly as it would for an envelope fetched over HTTPS;
  2. MUST apply the freshness, safe-to-quote and fail-closed rules (Core §6–§8);
  3. MUST take the guest to the direct_booking_url inside the verified payload, and to nothing else (Core §5.1);
  4. SHOULD treat tool descriptions as untrusted text.

A tool call is not a signed artifact (MCP composition profile). It is one more way to fetch the signed document.

9. Where the surfaces live (informative)

This version adds no field to the discovery document. Agents find a node's surfaces by each surface's own convention:

A future revision MAY add an optional discovery field that lists a node's surfaces.

10. Conformance

A node conforms to this document when, for every tool surface it exposes:

  1. the surface lists exactly one capability named get_verified_stay_offer (§3);
  2. that capability takes check_in, check_out and guests, and requires nothing else (§4);
  3. its result for given arguments is the same signed envelope the node's verified stay offer endpoint returns for the same arguments, and that envelope verifies against the node's JWKS with canonical_domain equal to the surface's domain (§5, §6).

The name check is three reads of the node and one comparison: the MCP tool list, the agent card's skill ids and the page's registered tool name are either one string or they are not. Conformance vectors for this document (a node's three surfaces and the expected outcome) are to be added to examples/conformance/ before it leaves proposal status (GOVERNANCE.md §4, §6).

11. Security considerations

12. Privacy considerations

The arguments are two dates and a guest count, as in Core §4 and §15. A node MUST NOT require guest-identifying input to return the offer. An agent SHOULD NOT send more than the three arguments.

13. Relationship to other documents

14. Reference implementation (informative)

The reference node, villaakerlyckan.se, exposes the capability on all three surfaces under the bound name, with the arguments of §4 and the result of §5. Read from production on 2026-10-21 (UTC): the node's MCP manifest, its agent card and its page name the capability get_verified_stay_offer, one string on all three. The platform that operates the node lists its own offer tool under an operator-namespaced name (vrp_get_verified_stay_offer), per §7. HemmaBo is a reference implementer, not an approval authority.

15. Open questions (for discussion in #156)

  1. Should the discovery document gain an optional field that lists a node's tool surfaces, or is each surface's own well-known convention enough?
  2. Should the WebMCP binding also bind the inputSchema byte for byte, or only the three argument names and types?
  3. Should operator tools be required (MUST) rather than recommended (SHOULD) to carry a namespace prefix?

16. Neutrality

The spec is vendor-neutral. HemmaBo is a reference implementer, not an approval authority. Any node, on any stack, can expose the capability under this name, and any agent can verify the result without permission from anyone.

17. License

Specification text: dedicated to the public domain under CC0 1.0.