Add server instructions + clarify tool descriptions - #189
Open
SynthLuvr wants to merge 6 commits into
Open
Conversation
) The server advertised five overlapping tools with no server-level 'instructions' and only isolated per-tool descriptions, so agents picked the wrong tool or misused them (e.g. calling tavily_extract as a search, or reading .results on what is actually a text return). - Add an 'instructions' string to the Server constructor (ServerOptions) so clients that surface it (Goose, Claude, Cursor) get a tool-selection decision tree, tool-combination guidance (search->extract, map->crawl), and the return format: every tool returns ONE markdown text string, not a JSON object. - Rewrite all five per-tool descriptions (ListTools handler + listTools() helper) to state when to use each tool, how they combine, and that the return value is plain text with no .results/.answer. Backwards compatible; no change to API calls themselves.
Only tavily_search and tavily_extract work without TAVILY_API_KEY; crawl/map/research return an 'API key required' message at call time (issue tavily-ai#188). - instructions: replace the inaccurate 'All tools require TAVILY_API_KEY' line with mode-aware text (keyless vs keyed). - Add describeTool() helper that appends a 'requires API key' note to crawl/map/research descriptions when IS_KEYLESS, in both the ListTools handler and the listTools() CLI helper. Advertised tool set unchanged (annotation, not omission).
SynthLuvr
marked this pull request as ready for review
July 17, 2026 11:27
The README listed only four tools (search, extract, map, crawl) despite the server exposing five. Add tavily_research throughout: - Replace the intro bullet list with a five-tool summary table - Add a usage note explaining when to prefer research over search (addresses the agent tool-selection confusion described in issue tavily-ai#188) - Add a dedicated tavily_research section with parameter reference, example, and notes on rate limits, credit cost, and response format - Update the Claude Code setup section to mention all five tools Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove the standalone endpoint section and decorative emojis in response to review feedback. Co-authored-by: Cursor <cursoragent@cursor.com>
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
2 participants
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.
Fixes #188.
tavily-mcpadvertises five overlapping tools (tavily_search,tavily_research,tavily_extract,tavily_crawl,tavily_map) but provided no server-levelinstructionsand only isolated per-tool descriptions. As a result, agents frequently pick the wrong tool or misuse them (e.g. callingtavily_extractas a search, passing a query instead of URLs), andtools/listgave no guidance on which tool to start with or how they combine. Issue #188 also flagged that in keyless mode the server advertises tools that cannot actually run.Changes
1. Add a server-level
instructionsstring (the canonical MCP field) to theServerconstructor'sServerOptions. Clients that surfaceinstructions(Goose, Claude, Cursor) now get:tavily_searchis the default; escalate totavily_researchonly for broad multi-source synthesis;tavily_extract/crawl/mapare URL/site-scoped),search->extract;map->crawl),2. Rewrite all five per-tool descriptions (both the
ListToolsrequest handler and thelistTools()helper, kept consistent) to state when to use each tool, how they combine, and that the return value is plain text.3. Surface keyless-mode limitations (second half of #188). In keyless mode (no
TAVILY_API_KEY), onlytavily_searchandtavily_extractwork;crawl/map/researchreturn an 'API key required' message at call time. Now reflected in the advertisement:instructionsAPI-key note is mode-aware (replacing the inaccurate 'All tools require TAVILY_API_KEY' line).describeTool()helper appends a 'requires API key' note to thecrawl/map/researchdescriptions only when keyless, in both theListToolshandler and thelistTools()CLI helper. The advertised tool set is unchanged (annotation, not omission) for backwards compatibility.Compatibility
instructionsis an optional field; no tool name, schema, or API-call behavior changes.Verification
Verified end-to-end with an MCP stdio client against the built server (
0.2.21), in both keyed and keyless modes:initializereturnsinstructions(mode-aware; the keyless branch lists which tools are available).tools/listreturns the updated descriptions;crawl/map/researchcarry the keyless note only whenTAVILY_API_KEYis unset;search/extractare always clean.crawl/map/researchwhile keyless returns the expected 'API key required' message (no errors).tsc --noEmit(strict) andnpm run buildpass; all 5 tools remain present with unchanged schemas.