Proposal: site guide for agents — a declarative map of screens, tools and workflows (pre-navigation, complements page-scoped tools)

Read the related proposals #161, #166 and #242, then review the live example at https://app.ainote.dev/.well-known/agent-guide.json and the discovery options in the issue. The open questions concern scope, discovery, tool naming and whether to converge with other manifests, so the change is complete when the group agrees on those semantics and documents the resulting proposal.

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

• #161 (Skills) puts workflow guidance on a loaded page through registerSkill(). A site guide is the static, pre-navigation counterpart and could reference skill names the same way it references tools.
• #166 proposes a signed /.well-known/webmcp.json that describes tool schemas for pre-flight discovery. This proposal stays one level up: screens and workflows, no schemas, no capability claims.
• #242 discusses an app-to-agent manifest.

Questions

1. Is a site-level guide in scope for this group, or better as a separate companion note?
2. <link rel> only, well-known only, or both?
3. Should tools stay names only, or allow a schema hash so agents can detect drift?
4. Should this converge with llms.txt or A2A/MCP "cards" into one well-known document?