Use a dependency when a tool needs another tool's data before it can execute. Use navigation when the user browses a list and a choice should start the next tool. Use a reference when a selected value should be reusable later without forcing an immediate next step.
Read dependencies first; the selection paths follow the same item-relative rules.
Browse categories, then list products
This complete config expects the categories API to return { data: [{ code: "hair", label: "Hair care" }] }. The products API response is displayed as raw data.
version: "2"
tools:
- id: categories
tool:
description: Browse product categories before viewing their products.
input_schema:
type: object
properties: {}
request:
method: GET
url: https://api.example.com/categories
selection:
items_path: $.data
id_path: $.code
label_path: $.label
navigates_to:
tool: products
map:
$.category_id: $.code
- id: products
tool:
description: List products in a category.
input_schema:
type: object
properties:
category_id: { type: string }
required: [category_id]
request:
method: GET
url: https://api.example.com/categories/{category}/products
map:
path:
category: $.category_id
Invoke categories. Its top-level selection and navigates_to turn the returned list into a choice. Pass the chosen option to runtime.select(). The selected item's code becomes products.category_id, then the path mapping builds /categories/hair/products.
The second tool must exist, declare the destination input, and define its HTTP contract. Merely writing navigates_to.tool: products does not create that tool.
If products is instead a confirmed write, its normal dependency and confirmation policies still apply. Navigation does not bypass them.
Carry original input separately from selected data
# Fragment on a source tool whose schema declares date and notes.
navigates_to:
tool: book
arguments:
date: $.date
notes: $.notes
map:
$.slot_token: $.slot_token
arguments reads source-tool input. map reads the chosen API item and writes destination-tool input. Here date and notes survive the browsing step, while slot_token comes from the selected item.
Both destination fields must exist in the target schema. The compiler rejects overlapping argument/map destinations, undeclared targets, and selection-display facts used as execution arguments. Keep the value's owner explicit.
Remember a selected service for a later tool
On a service-list tool that participates in an explicit selection, publish:
references:
publish:
name: selected_service
path: $.id
ttl_ms: 60000
When a service is actually selected, the runtime stores its id. It does not publish every item or guess the last item. Publication paths read the selected item; whole-item and private-field publication are rejected.
On a later tool whose schema declares service_id:
references:
consume:
service_id: selected_service
A valid reference fills an absent input and hides the top-level field from the model-facing schema. An explicitly supplied host/navigation input takes precedence. To resolve the value after expiry, give the consumer a suitable when: missing dependency. A reference is a convenience, not permanent authority.
Reference TTL defaults to 600,000 ms but cannot extend the originating selection's expiry. Context changes and cancellation invalidate reuse. Test the expired-reference path; do not assume the user always arrives through the same screen.
Keep labels separate from executable identifiers
# Selection fragment:
items_path: $.slots
id_path: $.slot_token
label_path: $.label
id_sensitive: true
facts:
time: $.label
facts.time supports conversational context and confirmation previews. It cannot supply an HTTP value. id_sensitive returns opaque option IDs to the host; pass them unchanged to select(), which recovers the internal item.
An opaque ID does not authorize a user to another user's session. The host still owns authentication and session binding.
Verify both the transition and the fallback
Use an API fixture with two categories. Assert categories executes first, then only the selected category is passed to products. Test invalid choice IDs, expired choices, a missing category code, and a reference that expires before consumption. For a write target, assert zero writes until approval.
Continue with the booking walkthrough for selection facts in a real confirmation preview.