feat: improve AI agent discoverability — tool descriptions, AGENTS.md, README#35
Merged
dbhurley merged 2 commits intoplasmate-labs:masterfrom Apr 2, 2026
Merged
Conversation
Tool descriptions (src/mcp/tools.rs): - fetch_page: '10x token savings' → '17x fewer tokens (up to 117x on complex pages)'. Added guidance: 'Prefer this over raw HTTP fetches for any web content in agent pipelines. Add selector=main to strip nav/footer and reduce tokens further.' - extract_text: added when-to-use guidance vs fetch_page - open_page: added when-to-use guidance for multi-step interaction These descriptions are what Claude/GPT-4/Cursor read when deciding which tool to call. Action-oriented instructions beat feature lists. AGENTS.md: - Codebase map for AI coding agents (Cursor, Devin, Claude Code) - Build/test instructions - How to add a new MCP tool (step-by-step) - Tool description writing guidelines - SOM selector reference table - Common patterns and anti-patterns (V8 callback threading, error handling, selector contract)
The @plasmate/ai package does not exist yet. Replace with a working code sample using the AI SDK's built-in MCP client (experimental_createMCPClient + StdioMCPTransport), which is available in AI SDK v4+ today. Links to official Vercel AI SDK MCP docs for reference.
|
@dbhurley is attempting to deploy a commit to the dbh ventures Team on Vercel. A member of the Team first needs to authorize it. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three improvements that make Plasmate easier to discover and use correctly by AI coding agents and agent pipelines:
1. Tool description rewrites (src/mcp/tools.rs)
Tool descriptions are what Claude, GPT-4, Cursor, and other agents read when deciding which tool to call. Action-oriented guidance beats feature lists.
fetch_page: '10x token savings' → '17x fewer tokens (up to 117x on complex pages). Prefer this over raw HTTP fetches for any web content in agent pipelines. Addselector='main'to strip nav/footer and reduce tokens further.'extract_text: added when-to-use guidance vsfetch_page— 'Use this (instead of fetch_page) when you only need the written content and do not need to interact with the page or reference specific elements.'open_page: added when-to-use guidance — 'Use this (instead of fetch_page) when you need to interact with the page — click buttons, fill forms, navigate, or run JavaScript. Pair with click, type_text, navigate_to, and evaluate.'The 17x/117x figures come from the published 51-URL benchmark (plasmate-benchmarks PR #1).
2. AGENTS.md
A guide for AI coding agents (Cursor, Devin, Claude Code, Copilot). Covers:
3. README 'For AI Agents' section
Added a dedicated section covering MCP setup for all major agent hosts (Claude Desktop, Cursor, VS Code Copilot, Windsurf), a working Vercel AI SDK example via the MCP client, and links to llms.txt and AGENTS.md.
The Vercel AI SDK example uses
experimental_createMCPClient+StdioMCPTransport(AI SDK v4+, no new package required).Context: Plasmate is now listed on the MCP Registry as the first browser/web tool. This PR ensures agents that encounter Plasmate — in registry listings, llms.txt, or installed MCP configs — get clear guidance on which tool to use and when.