Skip to content

Add an agent-tools projection: the tools agents call, on every surface - #11

Merged
agorischek merged 1 commit into
mainfrom
agent-tools-projection
Nov 17, 2026
Merged

agorischek merged 1 commit into
mainfrom
agent-tools-projection

Conversation

@agorischek

@agorischek agorischek commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

A projection of the tools Projections exposes to coding agents: each tool, its parameters (name, type, enum values, limits, required) and the surfaces that expose it (projections mcp, MCP Apps hosts, VS Code's languageModelTools, the Copilot app canvas).

Extraction (.github/projections/agent-tools/, custom, determinism: pure, scoped to six files): reads source at each revision, never runs the CLI, so history extracts without building it.

  • catalog.rs is evaluated from its Rust literals (json!, the file's helpers, format!, consts, struct literals); anything else fails with its line.
  • VS Code: the committed manifest. Canvas: the actions list and its project input. MCP Apps: app.rs's viewer_request and the tools linked to the view.
  • Verified: the evaluated catalog plus MCP Apps additions deep-equals a live projections mcp tools/list from an MCP Apps client; agent-tools.test.mjs checks it against the VS Code manifest.

Renderer: built-in api, one row per surface, tool (compare on mcp, mcp-apps, vscode · read-only · trust: extract) and parameter (definition?: "base" | "head"). Parameters a surface adds to every tool (folder, project) appear once, on its surface row.

Comparator (agent-tools.comparator.yaml) writes metadata.compatibility, so the api renderer counts levels and offers Breaking only:

  • breaking: a tool or parameter removed (from one surface too), a parameter made required, an enum value or type dropped, a range narrowed; behavioral: a tool that starts writing or needs more trust.
  • additive: a new tool, parameter or surface, a parameter made optional, values widened.
  • Surface drift (metadata.surfaceParity, the change's summary and the renderer's notices): a tool missing from a surface every tool should be on (options.everyTool), a canvas action not in the catalog, a parameter missing from a surface its tool is on (except options.dropped: VS Code's confirm), or with a different schema there. For VS Code it says to run node scripts/tools.mjs.
  • 5 cases over one fixture pair cover every rule.

Bookmarks: #7 (compare.definitionRevision: 1 additive change) and #9 (viewer on open_projection, current_view, refresh and screenshot: 4 additive changes); projections bookmark run --trust runs both.

Checks: projections check -p agent-tools --trust (all pass, renderer checks included), projections bookmark run --trust, cargo test -p projections-cli --test comparator_tests, node --test .github/projections/agent-tools/agent-tools.test.mjs, npm run docs:check, check:considered, check:links, check:boundaries, check:portability, oxfmt and eslint.

The tools Projections offers coding agents, their parameters and the surfaces
that expose them (projections mcp, MCP Apps hosts, VS Code's
languageModelTools and the Copilot app canvas), as one api/v0 extraction drawn
by the built-in api renderer.

- The extractor reads source, never runs the CLI: it evaluates the catalog's
  Rust literals (json!, helpers, format!, consts), and reads the VS Code
  manifest, the canvas's actions and the MCP Apps additions. Any revision
  extracts, built or not. A test checks the evaluated catalog against the VS
  Code manifest, which CI keeps equal to the CLI's tools/list.
- Its comparator classifies each change as agents calling the tools meet it,
  in the metadata.compatibility shape the api renderer counts and filters
  (a parameter removed, made required or narrowed is breaking; a tool that
  starts writing or needs more trust breaks behavior), and flags drift between
  surfaces (a tool or parameter on one but not another, or a stale VS Code
  manifest) in the summary, the renderer's notices and metadata.surfaceParity.
- Bookmarks #7 (compare takes definitionRevision) and #9 (the view tools take
  viewer); the agent tools doc mentions it.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@agorischek
agorischek requested a review from a team as a code owner November 17, 2026 17:29
@agorischek
agorischek merged commit 3d0ce4c into main Nov 17, 2026
92 of 94 checks passed
@agorischek
agorischek deleted the agent-tools-projection branch November 17, 2026 18:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant