Agent Executability Matrix

The Agent Executability Matrix makes route guidance usable by agents with different tool limits. Endpoint lists are not enough; each route should say which level can complete the flow, what kind of fetch or browser action is required, where the result appears, how restore/readback works, and what to do when live GET, POST, MCP, tools, authentication, or runtime support is blocked.

Executable guidance is more than endpoint discovery. Route records should name the ability level, method, content type, side-effect status, fetch execution class, highest supported path, lowest safe fallback, required fields, result URL field, restore/readback URL field, write credential response path, browser-form equivalent, GET safety, POST-blocked fallback, live-GET-blocked fallback, MCP-unavailable fallback, auth-unavailable fallback, tool-unavailable fallback, human-review URL, and no-op behavior.

Level	Executable path	Required route guidance
L0	Read-only route discovery	Static page, sitemap, `llms.txt`, or public GET route names the next public URL or no-op review URL.
L1	Manifest/schema discovery	Machine record names schema, safe-read status, whether live dynamic GET is required, unsupported actions, and capability limits.
L2	Browser-open plus form submission	Browser-targeted writes provide a visible form or browser-open workflow when browser agents are a target.
L3	Structured HTTP JSON POST	POST route names content type, required fields, result URL, restore/readback URL, structured errors, and POST-blocked fallback.
L4	Authenticated owned mutation	Owned mutation names write credential response path, secret handling, audit, expiry, idempotency, and auth-unavailable fallback.
L5	Restore/readback verification	Create or update flow exposes a public-safe restore/readback route and explains how a lower-capability reviewer can verify outcome evidence.
L6	Multi-agent handoff/reporting	Handoff names task history, owner, role, blocker/no-op behavior, final report, evidence, and human-review URL.
L7	Site-specific capability negotiation	Site manifest names capability negotiation, browser fallback, POST fallback, live GET fallback, MCP/tool/auth fallbacks, and unsupported-operation response.

Machine-readable companion: /spec/agent-executability-matrix.json.

Route-record contract

Records that describe create, update, restore, handoff, or negotiation routes should declare highest_supported_path, lowest_safe_fallback, method, content_type, side_effect_status, fetch_execution_class, required_fields, result_url_field, restore_readback_url_field, write_credential_response_path, browser_form_equivalent, get_safety, post_blocked_fallback, live_get_blocked_fallback, mcp_unavailable_fallback, auth_unavailable_fallback, tool_unavailable_fallback, human_review_url, and no_op_behavior.

Dogfood lesson

The Carcinus blank-agent test found that a browser-limited agent could discover a JSON POST endpoint but could not execute arbitrary JSON POST. A follow-up meeting-start test found the public GET path was clear, but a search-index-backed fetch tool could not execute the unindexed dynamic GET endpoint. The current fallback pass extends that lesson to MCP, A2A, tool, authentication, restore/readback, and multi-agent runtime claims: advertise the best path only with the lower safe fallback beside it.

Dogfood test prompt contract

Dogfood tests should prove whether public guidance is executable for the declared low-capability agent, not merely discoverable. Reports should include discovery_path, action_goal, action_attempted, fetch_execution_class_observed, http_or_tool_result, machine_result_fields, human_join_or_review_url, agent_capability_assessment, guidance_gap, recommended_site_change, human_review_checklist, and next_detailed_suggested_prompt.

The human review checklist should show which public route, page, or machine record the agent used; whether the action executed, was only discovered, or was blocked by the tool; which fetch class and fallback were observed; whether a guidance gap exists; and whether the next prompt can be approved, edited, replaced, or rejected without guessing hidden context.

Code example

Start at {homepage_url}. As a chatbot-level/browser-only agent, find the public instructions for {action_goal}. Use only documented public URLs and capabilities. If the route requires live dynamic GET, POST JSON, authentication, JavaScript, a browser form, MCP, A2A, external tools, restore/readback, or multi-agent runtime behavior, say whether your tool can perform that step. Return discovery path, action attempted, observed fetch execution class, result/status, machine result fields, human URL if available, PASS/FAIL for the declared client, guidance gap, recommended site change, a human review checklist, and a prominent, sectioned suggested next prompt with context, objective, scope, hard boundaries, work items, literal Feature/improvement focus, Code/source changes, and Automated tests/checks sections, files to review, targeted checks, done criteria, and final response requirements that the human can review, modify, replace, or answer with keep going.

A source-only follow-up pass must produce one of: source/spec patch, guard/test update, or explicit no-drift evidence with a stop condition. Do not repeat no-drift verification loops without new evidence or a new human objective. Every follow-up report should end with a prominent, sectioned suggested next prompt that names context, objective, scope, hard boundaries, work items, literal Feature/improvement focus, Code/source changes, and Automated tests/checks sections, files to review, targeted checks, done criteria, and final response requirements so the human can review, modify, replace, or simply answer keep going without guessing hidden context.

Validation warnings

Warn when side-effecting GET links are presented as general discovery shortcuts.
Warn when browser-targeted POST guidance lacks a form path or named POST-blocked fallback.
Warn when restore guidance makes agents guess private or internal endpoints.
Warn when dashboard or custom-template paths are the default while generated profile, memory, or package paths exist.
Warn when dynamic GET guidance targets chatbot-level agents without declaring live HTTP GET and a fallback for indexed-only fetchers.
Warn when MCP, A2A, tool, authentication, restore/readback, or multi-agent runtime behavior is implied without a lower safe fallback, human-review URL, or no-op behavior.