Summary
A site may publish a small, declarative site guide: a map of its screens, which WebMCP tools are useful where, and a few common workflows. It is a hint for planning, not a tool manifest and not a permission grant. The tools a page actually registers stay the source of truth.
A live example is running now: https://app.ainote.dev/.well-known/agent-guide.json, linked from every page with <link rel="agent-guide" href="/.well-known/agent-guide.json">.
Problem
WebMCP tools are registered by a loaded document, so an agent discovers them only after it reaches the right page. Keeping tools page-scoped is the right call, because tools depend on page state and authentication. But it leaves agents with no cheap answer to the questions they ask first:
- What screens does this site have, and which one can do what I need?
- Is the tool I want available everywhere, or only on one screen? Do I need to sign in?
- What is the usual sequence of steps for a common task?
Agents fill the gap by crawling, which is costly and risky with side-effecting GETs, or by guessing from menus. Small on-device or on-prem models struggle the most. We see this with an 8B local model in a closed-network agent browser: it can work out menus, page kinds, forms and tables, but every inference step costs tokens and adds errors.
Repositories solved the same problem with AGENTS.md, and content sites with llms.txt and sitemap.xml. Interactive web apps need an equivalent that sits next to WebMCP.
Sketch
Discovery: <link rel="agent-guide"> and/or /.well-known/agent-guide.json. Same origin only.
{
"version": 1,
"site": { "name": "AI Note", "description": "Tasks, notes, calendar and a synced wiki" },
"sections": [
{
"id": "tasks", "title": "Tasks", "url": "/tasks", "urlPattern": "/tasks*",
"kinds": ["list", "search", "filter"],
"tools": ["search_tasks", "list_tasks", "create_task"],
"writes": ["create_task"],
"requiresAuth": true
},
{
"id": "task-detail", "title": "Task detail", "urlPattern": "/tasks/:id",
"kinds": ["detail", "form"],
"summary": "update_task / complete_task use the task in the URL when no task_id is given; delete_task always needs task_id.",
"tools": ["update_task", "complete_task", "delete_task"],
"writes": ["update_task", "complete_task", "delete_task"],
"requiresAuth": true
}
],
"workflows": [
{
"id": "weekly-review", "title": "Summarise this week's open tasks",
"steps": [
{ "section": "tasks", "tool": "list_tasks", "hint": "is_completed=false, start_date/end_date = this week" },
{ "section": "calendar", "tool": "get_calendar_events", "hint": "once per day with date=YYYY-MM-DD" }
]
}
]
}Semantics:
tools only names tools the page is expected to register. If the guide and the live registerTool() disagree, the page wins.writes marks tools that change data, so an agent can plan confirmations up front. It does not replace per-call annotations such as readOnlyHint or user confirmation.workflows are hints written by the site. They carry the kind of knowledge a tool description can't hold, such as "this tool refuses the note that is open in the editor; append from another page".
Security considerations
- Treat the guide as untrusted, site-authored text, like tool descriptions. It must not grant permissions, change confirmation policy, or be placed in a system prompt as instructions.
- Agents must not auto-navigate to every section. Navigation still follows the user's task and the browser's policies.
- A malicious guide could steer an agent toward phishing-like flows within its own origin. The same-origin rule, the "page wins" rule and showing the origin in UI limit this.
What we learned writing the live example
We checked every path and tool name against the app's routes and WebMCP code. Getting the guide right took several review passes, and most corrections were behaviour that a tool's schema doesn't show: which tools act on "the current page", which need explicit IDs, and which accept a date but not a range. That is the information a planner most needs before choosing a page.
Related
Questions
- Is a site-level guide in scope for this group, or better as a separate companion note?
<link rel> only, well-known only, or both?- Should
tools stay names only, or allow a schema hash so agents can detect drift?
- Should this converge with
llms.txt or A2A/MCP "cards" into one well-known document?
Summary
A site may publish a small, declarative site guide: a map of its screens, which WebMCP tools are useful where, and a few common workflows. It is a hint for planning, not a tool manifest and not a permission grant. The tools a page actually registers stay the source of truth.
A live example is running now: https://app.ainote.dev/.well-known/agent-guide.json, linked from every page with
<link rel="agent-guide" href="/.well-known/agent-guide.json">.Problem
WebMCP tools are registered by a loaded document, so an agent discovers them only after it reaches the right page. Keeping tools page-scoped is the right call, because tools depend on page state and authentication. But it leaves agents with no cheap answer to the questions they ask first:
Agents fill the gap by crawling, which is costly and risky with side-effecting GETs, or by guessing from menus. Small on-device or on-prem models struggle the most. We see this with an 8B local model in a closed-network agent browser: it can work out menus, page kinds, forms and tables, but every inference step costs tokens and adds errors.
Repositories solved the same problem with
AGENTS.md, and content sites withllms.txtandsitemap.xml. Interactive web apps need an equivalent that sits next to WebMCP.Sketch
Discovery:
<link rel="agent-guide">and/or/.well-known/agent-guide.json. Same origin only.{ "version": 1, "site": { "name": "AI Note", "description": "Tasks, notes, calendar and a synced wiki" }, "sections": [ { "id": "tasks", "title": "Tasks", "url": "/tasks", "urlPattern": "/tasks*", "kinds": ["list", "search", "filter"], "tools": ["search_tasks", "list_tasks", "create_task"], "writes": ["create_task"], "requiresAuth": true }, { "id": "task-detail", "title": "Task detail", "urlPattern": "/tasks/:id", "kinds": ["detail", "form"], "summary": "update_task / complete_task use the task in the URL when no task_id is given; delete_task always needs task_id.", "tools": ["update_task", "complete_task", "delete_task"], "writes": ["update_task", "complete_task", "delete_task"], "requiresAuth": true } ], "workflows": [ { "id": "weekly-review", "title": "Summarise this week's open tasks", "steps": [ { "section": "tasks", "tool": "list_tasks", "hint": "is_completed=false, start_date/end_date = this week" }, { "section": "calendar", "tool": "get_calendar_events", "hint": "once per day with date=YYYY-MM-DD" } ] } ] }Semantics:
toolsonly names tools the page is expected to register. If the guide and the liveregisterTool()disagree, the page wins.writesmarks tools that change data, so an agent can plan confirmations up front. It does not replace per-call annotations such asreadOnlyHintor user confirmation.workflowsare hints written by the site. They carry the kind of knowledge a tool description can't hold, such as "this tool refuses the note that is open in the editor; append from another page".Security considerations
What we learned writing the live example
We checked every path and tool name against the app's routes and WebMCP code. Getting the guide right took several review passes, and most corrections were behaviour that a tool's schema doesn't show: which tools act on "the current page", which need explicit IDs, and which accept a date but not a range. That is the information a planner most needs before choosing a page.
Related
registerSkill(). A site guide is the static, pre-navigation counterpart and could reference skill names the same way it references tools./.well-known/webmcp.jsonthat describes tool schemas for pre-flight discovery. This proposal stays one level up: screens and workflows, no schemas, no capability claims.Questions
<link rel>only, well-known only, or both?toolsstay names only, or allow a schema hash so agents can detect drift?llms.txtor A2A/MCP "cards" into one well-known document?