diff --git a/docs/api/rest-api.md b/docs/api/rest-api.md index 1bd4215e0..5e521aad7 100644 --- a/docs/api/rest-api.md +++ b/docs/api/rest-api.md @@ -758,7 +758,7 @@ See [Routing Modes](../features/routing-modes.md) for details on each mode. The MCP endpoints (not REST) additionally expose progressive-disclosure discovery in the `retrieve_tools` routing mode: -- **`tool_response_mode`** config (`full` default | `compact`, hot-reloadable via `POST /api/v1/config/apply`) controls `retrieve_tools` serialization only. In `compact` mode each entry is `{id, score, sig, desc, lossy}` — a one-line parameter signature (`*` = required, `~` = lossy) plus a first-sentence description — instead of full `inputSchema`, and the response carries one top-level `hint` line. Ranking is identical between modes. +- **`tool_response_mode`** config (`full` default | `compact`, hot-reloadable via `POST /api/v1/config/apply`) controls `retrieve_tools` serialization only. In `compact` mode each entry is `{id, score, sig, desc, lossy, call_with}` — a one-line parameter signature (`*` = required, `~` = lossy), a first-sentence description, and the same dispatch route as full mode — instead of full `inputSchema`, and the response carries one top-level `hint` line. If upstream tier annotations are unavailable, `call_with` preserves the existing read fallback. Ranking is identical between modes. - **`detail`** — optional per-call `retrieve_tools` parameter (`compact` | `full`) overriding the configured mode for that call. - **`describe_tool`** — built-in second-stage tool (retrieve_tools mode only): accepts 1–5 `server:tool` ids and returns full definitions (`name`, `description`, `inputSchema`, `server`, `annotations`, `call_with`) with per-id errors for ids that do not resolve. It applies the same visibility pipeline as search (profile scope, agent-token scope, quarantine, tool approval, disabled) and never returns a definition `retrieve_tools` could not. Per-id error codes: `not_found`, `quarantined`, `pending_approval`, `changed`, `disabled` (Spec 099 retired `invisible`: an out-of-scope id now reports `not_found`, indistinguishable from an id that does not exist — see the [breaking-change note](https://github.com/smart-mcp-proxy/mcpproxy-go/blob/main/CHANGELOG.md)). - **`describe_tool` check mode (Spec 099)** — the same built-in with `check: true` answers availability instead of definitions: up to 50 ids, an optional `filters` object (`read_only_only`, `exclude_destructive`, `exclude_open_world` — the REST body of `POST /api/v1/preflight` calls the same object `policy`), and a response of `{verdict, checked_at, request_id, results[]}` carrying the same reason codes this endpoint returns. It is the in-band twin of `POST /api/v1/preflight`, evaluated by the same evaluator, and differs deliberately: always the agent-token disclosure tier (never a hash, never `server_not_in_scope`), the session's own scope with no `profile` parameter, no hash pins (`expect_hashes` is a reserved field name and is rejected), and no wait budget. See [Required-Tools Preflight](../features/tools-preflight.md#in-band-describe_tool-check-mode). diff --git a/docs/configuration.md b/docs/configuration.md index c773b0594..6a7c743bd 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1394,7 +1394,7 @@ Controls only the *serialization* of `retrieve_tools` responses (Spec 085) — n | Field | Type | Default | Description | |-------|------|---------|-------------| -| `tool_response_mode` | string | `"full"` | `full` returns complete `inputSchema` entries (pre-Spec-085 behavior, byte-identical). `compact` returns one-line signatures instead: per entry `id`, `score`, `sig`, first-sentence `desc`, and a `lossy` flag, plus one top-level `hint` line. | +| `tool_response_mode` | string | `"full"` | `full` returns complete `inputSchema` entries (pre-Spec-085 behavior). `compact` returns one-line signatures instead: per entry `id`, `score`, `sig`, first-sentence `desc`, a `lossy` flag and the same `call_with` route as full mode, plus one top-level `hint` line. | - **Compact signatures**: `*` marks a required parameter (never elided), `~` marks a lossy collapse (nested objects, long enums — call `describe_tool` for the full schema), short enums/defaults are inlined (e.g. `(origin*:str, ttl:int=3600)`). - **Per-call override**: the `detail` parameter on `retrieve_tools` (`compact` | `full`) overrides the configured mode for that call only. diff --git a/docs/features/search-discovery.md b/docs/features/search-discovery.md index 72878e625..ddee6227b 100644 --- a/docs/features/search-discovery.md +++ b/docs/features/search-discovery.md @@ -108,7 +108,7 @@ the query, the ranking, or which tools are found. | Option | Type | Default | Values | Description | |--------|------|---------|--------|-------------| -| `tool_response_mode` | string | `"full"` | `full`, `compact` | `full` returns each result with its complete `inputSchema` (pre-Spec-085 behaviour, byte-identical). `compact` returns a one-line signature instead: per entry `id`, `score`, `sig`, a first-sentence `desc` and a `lossy` flag, plus one top-level `hint`. An empty value means `full`. | +| `tool_response_mode` | string | `"full"` | `full`, `compact` | `full` returns each result with its complete `inputSchema` (pre-Spec-085 behaviour). `compact` returns a one-line signature instead: per entry `id`, `score`, `sig`, a first-sentence `desc`, a `lossy` flag and the same `call_with` route as full mode, plus one top-level `hint`. An empty value means `full`. | - **Compact signatures**: `*` marks a required parameter (never elided), `~` marks a lossy collapse (nested objects, long enums), and short enums/defaults diff --git a/internal/contracts/intent.go b/internal/contracts/intent.go index d4ea04ba0..eba5f2cdf 100644 --- a/internal/contracts/intent.go +++ b/internal/contracts/intent.go @@ -197,8 +197,11 @@ func (i *IntentDeclaration) ValidateAgainstServerAnnotations(toolVariant, server } // DeriveCallWith derives the recommended tool variant from server annotations. -// Defaults to call_tool_read as the safest option when intent is unclear. -// LLMs should analyze the tool description to override this default when appropriate. +// Defaults to call_tool_read when no tier annotation is present. Agents are told +// that call_with is authoritative over a tool's name, description or the requested +// outcome (PR #1668), so this default is what an unannotated tool is routed through; +// the server-side tier gate and the profile `unannotated` policy, not the agent's +// guess, decide whether that call is admitted. // // Priority: // 1. destructiveHint=true → call_tool_destructive diff --git a/internal/server/mcp.go b/internal/server/mcp.go index b60a7d203..71e7ec97a 100644 --- a/internal/server/mcp.go +++ b/internal/server/mcp.go @@ -1165,7 +1165,7 @@ func buildCallToolVariantTool(variant string) mcp.Tool { switch variant { case contracts.ToolVariantRead: - description = "Execute a READ-ONLY tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. Examples: search_files, get_user, list_repositories, query_database, find_issues, check_status. This is the DEFAULT choice when unsure - most tools are read-only." + description = "Execute a READ-ONLY tool. Use this variant only when retrieve_tools returns call_with=call_tool_read. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first)." title = "Call Tool (Read)" nameExample = "github:get_user" sensitivityDesc = "Classify data being accessed: public, internal, private, or unknown. Helps track sensitive data access patterns." @@ -1176,7 +1176,7 @@ func buildCallToolVariantTool(variant string) mcp.Tool { mcp.WithOpenWorldHintAnnotation(true), } case contracts.ToolVariantWrite: - description = "Execute a STATE-MODIFYING tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. Examples: create_issue, update_file, send_message, add_comment, set_status, edit_page. Use only when explicitly modifying state." + description = "Execute a STATE-MODIFYING tool. Use this variant only when retrieve_tools returns call_with=call_tool_write. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first)." title = "Call Tool (Write)" nameExample = "github:create_issue" sensitivityDesc = "Classify data being modified: public, internal, private, or unknown. Helps track sensitive data changes." @@ -1187,7 +1187,7 @@ func buildCallToolVariantTool(variant string) mcp.Tool { mcp.WithOpenWorldHintAnnotation(true), } case contracts.ToolVariantDestructive: - description = "Execute a DESTRUCTIVE tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. Examples: delete_repo, remove_user, drop_table, revoke_access, clear_cache, terminate_session. Use for irreversible or high-impact operations." + description = "Execute a DESTRUCTIVE tool. Use this variant only when retrieve_tools returns call_with=call_tool_destructive. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. This variant does not bypass authorization, quarantine, approval, or other dispatch gates. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first)." title = "Call Tool (Destructive)" nameExample = "github:delete_repo" sensitivityDesc = "Classify data being deleted: public, internal, private, or unknown. Important for tracking destructive operations on sensitive data." @@ -1343,7 +1343,7 @@ const retrieveToolsDiagnosticsNote = " ANNOTATION FILTERS: read_only_only, exclu func (p *MCPProxyServer) registerTools(_ bool) { // retrieve_tools - THE PRIMARY TOOL FOR DISCOVERING TOOLS - Enhanced with clear instructions retrieveToolsOpts := []mcp.ToolOption{ - mcp.WithDescription("🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Results include 'annotations' (tool behavior hints like destructiveHint) and 'call_with' recommendation indicating which tool variant to use (call_tool_read/write/destructive). Then use the recommended variant with an 'intent' parameter. Compact mode returns one-line signatures ('sig': '*'=required, '~'=lossy) with first-sentence 'desc'; call describe_tool for full schemas. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers." + retrieveToolsReachNote + retrieveToolsDiagnosticsNote), + mcp.WithDescription("🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Follow each result's call_with route exactly; upstream annotations determine that route and take precedence over tool names, descriptions, command text, and requested outcome. Compact results preserve the same call_with route as full results, including the existing read fallback when upstream tier annotations are unavailable. Never infer a route from a tool's name or intent. Compact mode returns one-line signatures ('sig': '*'=required, '~'=lossy) with first-sentence 'desc'; call describe_tool for full schemas. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers." + retrieveToolsReachNote + retrieveToolsDiagnosticsNote), mcp.WithTitleAnnotation("Retrieve Tools"), mcp.WithReadOnlyHintAnnotation(true), mcp.WithDestructiveHintAnnotation(false), @@ -2402,7 +2402,8 @@ func (p *MCPProxyServer) handleRetrieveToolsWithMode(ctx context.Context, reques // construction lives in buildToolEntry (Spec 085 entry-builder seam) — // full mode is byte-identical to the pre-extraction inline code, guarded // by the T011 golden test (FR-006/SC-003); compact mode renders - // {id, score, sig, desc, lossy} from the shared signature cache. The + // {id, score, sig, desc, lossy, call_with} from the shared signature cache + // (call_with added by #1668 so compact routing never falls back to names). The // ranked order of `results` is already final here — the mode selects // serialization only (FR-007). entryOpts := toolEntryOpts{includeStats: includeStats} @@ -2439,11 +2440,7 @@ func (p *MCPProxyServer) handleRetrieveToolsWithMode(ctx context.Context, reques "Do NOT use call_tool_read, call_tool_write, or call_tool_destructive — they are not available in code execution mode." default: // Default instructions for retrieve_tools mode and backward-compatible callers - usageInstructions = "TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. " + - "DECISION RULES BY TOOL NAME: " + - "(1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. " + - "(2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. " + - "(3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. " + + usageInstructions = "TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. " + "INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing." } diff --git a/internal/server/mcp_entry_builder.go b/internal/server/mcp_entry_builder.go index 14ecde4d8..e89132dbb 100644 --- a/internal/server/mcp_entry_builder.go +++ b/internal/server/mcp_entry_builder.go @@ -15,7 +15,7 @@ import ( // "hint") to every compact-mode retrieve_tools response (Spec 085 FR-009). // It explains the lossy marker and the describe_tool second stage; being part // of the serialized payload it counts toward every measured response size. -const compactModeHint = "sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Before calling a tool whose entry is lossy:true, call describe_tool with its id to get the full input schema." +const compactModeHint = "sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Follow the call_with route exactly; it matches the full tool result, including the existing read fallback when no tier annotations are available. Never infer a route from the name, description, command text, or requested outcome. Before calling a lossy entry, call describe_tool for its full input schema." // toolEntryOpts carries the per-request options that shape one retrieve_tools // result entry (Spec 085 entry-builder seam, research.md R5). @@ -47,8 +47,9 @@ type toolEntryOpts struct { // built inline before the extraction — byte-identical under // json.Marshal, guarded by the T011 golden test (FR-006/SC-003). // - mode compact (US1, FR-002): {id, score, sig, desc, lossy} rendered -// from the shared p.sigCache — no inputSchema, no full description, no -// annotations (those move to describe_tool / self-healing errors). +// from the shared p.sigCache, plus the same call_with route as full mode. +// No inputSchema, full description, or annotations +// (those move to describe_tool / self-healing errors). // // Cross-cutting response sections (usage_instructions, disabled/remediation, // notice, session_risk, debug, usage_summary) intentionally stay in @@ -69,8 +70,9 @@ func (p *MCPProxyServer) buildToolEntry(result *config.SearchResult, mode string // here. // // include_stats is intentionally ignored in compact mode: the compact entry -// shape is fixed at exactly {id, score, sig, desc, lossy} (data-model §4); -// the top-level usage_summary section still renders in the handler. +// shape is {id, score, sig, desc, lossy, call_with}, with call_with derived +// from the same annotations and fallback as full mode; the top-level +// usage_summary section still renders in the handler. func (p *MCPProxyServer) buildCompactToolEntry(result *config.SearchResult) map[string]interface{} { tool := result.Tool @@ -94,13 +96,34 @@ func (p *MCPProxyServer) buildCompactToolEntry(result *config.SearchResult) map[ } } - return map[string]interface{}{ + entry := map[string]interface{}{ "id": tool.Name, "score": result.Score, "sig": sig.Sig, "desc": sig.Desc, "lossy": sig.Lossy, } + entry["call_with"] = p.compactToolCallWith(result) + return entry +} + +// compactToolCallWith mirrors buildFullToolEntry's route selection so compact +// entries preserve the existing dispatch classification, including its read +// fallback when no upstream tier hints are available. +func (p *MCPProxyServer) compactToolCallWith(result *config.SearchResult) string { + if result == nil || result.Tool == nil { + return contracts.ToolVariantRead + } + serverName := result.Tool.ServerName + toolName := result.Tool.Name + if serverName == "" { + parts := strings.SplitN(result.Tool.Name, ":", 2) + if len(parts) != 2 { + return contracts.ToolVariantRead + } + serverName, toolName = parts[0], parts[1] + } + return contracts.DeriveCallWith(p.lookupToolAnnotations(serverName, toolName)) } // buildFullToolEntry reproduces today's full-mode entry exactly diff --git a/internal/server/mcp_entry_builder_test.go b/internal/server/mcp_entry_builder_test.go index 5ea922209..d6a2e0d95 100644 --- a/internal/server/mcp_entry_builder_test.go +++ b/internal/server/mcp_entry_builder_test.go @@ -13,15 +13,17 @@ import ( "github.com/stretchr/testify/require" "github.com/smart-mcp-proxy/mcpproxy-go/internal/config" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/contracts" + "github.com/smart-mcp-proxy/mcpproxy-go/internal/runtime/stateview" "github.com/smart-mcp-proxy/mcpproxy-go/internal/storage" ) // Spec 085 T011 — full-mode byte-identity golden (FR-006/SC-003). // -// The golden files under testdata/ were captured from the retrieve_tools -// handler BEFORE the entry-builder extraction (T012) and the shared-visibility -// rewiring (T010), so any post-refactor byte difference in the full-mode -// response is a regression. Regenerate ONLY when a deliberate, spec-approved +// The golden files under testdata/ began as captures of the retrieve_tools +// handler BEFORE the entry-builder extraction (T012) and shared-visibility +// rewiring (T010). They pin the current full-mode bytes, including approved +// routing-guidance updates. Regenerate ONLY when a deliberate, spec-approved // response change lands: UPDATE_GOLDEN=1 go test ./internal/server -run // TestRetrieveToolsFullMode_GoldenByteIdentity // @@ -110,7 +112,7 @@ func compareGolden(t *testing.T, goldenPath, got string) { assert.Equal(t, strings.TrimRight(string(want), "\n"), strings.TrimRight(got, "\n"), - "full-mode retrieve_tools response must be byte-identical to the pre-refactor capture (FR-006/SC-003)") + "full-mode retrieve_tools response must be byte-identical to its committed golden (FR-006/SC-003)") } func TestRetrieveToolsFullMode_GoldenByteIdentity(t *testing.T) { @@ -227,11 +229,10 @@ func TestRetrieveToolsFullMode_MergeBaseFilterSemantics(t *testing.T) { // --- Spec 085 US1 T018 (FR-002): compact entry shape --- // -// A compact entry carries EXACTLY {id, score, sig, desc, lossy}: no -// inputSchema, no full description, no annotations block — those move to -// describe_tool / self-healing errors. id is derived exactly as the -// full-mode "name" (result.Tool.Name), so ranked order and identity are -// untouched by construction. +// A compact entry carries {id, score, sig, desc, lossy, call_with}: no +// inputSchema, full description, or annotations block — those move to +// describe_tool / self-healing errors. id is derived exactly as the full-mode +// "name" (result.Tool.Name), so ranked order and identity remain unchanged. func TestBuildToolEntry_CompactShape(t *testing.T) { proxy := createTestMCPProxyServer(t) @@ -254,12 +255,85 @@ func TestBuildToolEntry_CompactShape(t *testing.T) { assert.Equal(t, "Create an issue to track work.", entry["desc"], "desc must be the verbatim first sentence") assert.Equal(t, false, entry["lossy"]) - assert.Len(t, entry, 5, "compact entry must carry exactly {id, score, sig, desc, lossy}") - for _, forbidden := range []string{"inputSchema", "description", "annotations", "name", "server", "call_with", "usage_count", "last_used"} { + assert.Equal(t, "call_tool_read", entry["call_with"], "unannotated tools preserve the full-mode read fallback") + assert.Len(t, entry, 6, "compact entries add the dispatch route to their five data fields") + for _, forbidden := range []string{"inputSchema", "description", "annotations", "name", "server", "usage_count", "last_used"} { assert.NotContains(t, entry, forbidden, "compact entries must not leak full-mode field %q", forbidden) } } +func TestBuildToolEntry_CompactPreservesExplicitCallRoute(t *testing.T) { + proxy, rt := createTestProxyWithRuntime(t, []*config.ServerConfig{{Name: "windows", Enabled: true}}) + tests := []struct { + name string + annotations *config.ToolAnnotations + want string + }{ + {name: "annotated read", annotations: &config.ToolAnnotations{ReadOnlyHint: boolPtr(true), DestructiveHint: boolPtr(false)}, want: "call_tool_read"}, + {name: "annotated write", annotations: &config.ToolAnnotations{ReadOnlyHint: boolPtr(false), DestructiveHint: boolPtr(false)}, want: "call_tool_write"}, + {name: "annotated destructive", annotations: &config.ToolAnnotations{ReadOnlyHint: boolPtr(false), DestructiveHint: boolPtr(true)}, want: "call_tool_destructive"}, + {name: "unannotated fallback", want: "call_tool_read"}, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + rt.Supervisor().StateView().UpdateServer("windows", func(status *stateview.ServerStatus) { + status.Enabled = true + status.Connected = true + status.ToolsDiscovered = true + status.Tools = []stateview.ToolInfo{{Name: "PowerShell", Annotations: tc.annotations}} + }) + for _, identity := range []struct { + name string + toolName string + serverName string + }{ + {name: "canonical id with server", toolName: "windows:PowerShell", serverName: "windows"}, + {name: "server inferred from canonical id", toolName: "windows:PowerShell"}, + {name: "bare name with server", toolName: "PowerShell", serverName: "windows"}, + } { + t.Run(identity.name, func(t *testing.T) { + result := &config.SearchResult{Tool: &config.ToolMetadata{ + Name: identity.toolName, ServerName: identity.serverName, + Description: "Run a PowerShell command.", + ParamsJSON: `{"type":"object","properties":{"command":{"type":"string"}},"required":["command"]}`, + Hash: "hash-powershell-route", + }} + + compact := proxy.buildToolEntry(result, config.ToolResponseModeCompact, toolEntryOpts{}) + full := proxy.buildToolEntry(result, config.ToolResponseModeFull, toolEntryOpts{}) + assert.Equal(t, tc.want, compact["call_with"]) + assert.Equal(t, full["call_with"], compact["call_with"], "compact and full routes must match") + assert.NotContains(t, compact, "annotations") + assert.NotContains(t, compact, "inputSchema") + }) + } + }) + } +} + +func TestCompactToolCallWith_MissingIdentityFallsBackToRead(t *testing.T) { + proxy := createTestMCPProxyServer(t) + for _, tc := range []struct { + name string + result *config.SearchResult + }{ + {name: "missing result"}, + {name: "missing tool", result: &config.SearchResult{}}, + {name: "empty identity", result: &config.SearchResult{Tool: &config.ToolMetadata{}}}, + {name: "bare name without server", result: &config.SearchResult{Tool: &config.ToolMetadata{Name: "PowerShell"}}}, + {name: "unknown server", result: &config.SearchResult{Tool: &config.ToolMetadata{Name: "unknown:PowerShell"}}}, + } { + t.Run(tc.name, func(t *testing.T) { + assert.Equal(t, contracts.ToolVariantRead, proxy.compactToolCallWith(tc.result)) + if tc.result != nil && tc.result.Tool != nil { + full := proxy.buildToolEntry(tc.result, config.ToolResponseModeFull, toolEntryOpts{}) + compact := proxy.buildToolEntry(tc.result, config.ToolResponseModeCompact, toolEntryOpts{}) + assert.Equal(t, full["call_with"], compact["call_with"]) + } + }) + } +} + func TestBuildToolEntry_CompactLossyNestedRequired(t *testing.T) { proxy := createTestMCPProxyServer(t) diff --git a/internal/server/mcp_filter_diagnostics_test.go b/internal/server/mcp_filter_diagnostics_test.go index fde7dab15..9251db5b5 100644 --- a/internal/server/mcp_filter_diagnostics_test.go +++ b/internal/server/mcp_filter_diagnostics_test.go @@ -126,11 +126,13 @@ func addAnnotatedTool(t *testing.T, proxy *MCPProxyServer, rt *runtime.Runtime, }) } -// --- T003: frozen pre-feature response goldens (SC-002) --- +// --- T003: frozen response goldens (SC-002) --- // -// Captured while the branch still had pre-feature behavior, these six files -// pin the EXACT bytes of the three response conditions in both serialization -// modes. Post-feature: +// These six files pin the exact bytes for the three response conditions in +// both serialization modes. They originate from the pre-filter-diagnostics +// capture and were updated only for the deliberate compact routing changes: +// the `call_with` field and authoritative routing guidance. The diagnostics +// feature is checked separately below. The current feature: // // (a) no filters -> byte-identical to the golden // (b) filters, no omissions -> byte-identical to the golden @@ -208,7 +210,7 @@ func compareSpec094Golden(t *testing.T, goldenPath, got string) { assert.Equal(t, strings.TrimRight(string(want), "\n"), strings.TrimRight(got, "\n"), - "response must be byte-identical to the frozen pre-feature capture (SC-002)") + "response must be byte-identical to the committed routing-contract golden (SC-002)") } // stripTopLevelJSONKey removes one top-level `"key": ` member from a diff --git a/internal/server/mcp_internal_annotations_test.go b/internal/server/mcp_internal_annotations_test.go index 1d7b9fe36..43fd59b3c 100644 --- a/internal/server/mcp_internal_annotations_test.go +++ b/internal/server/mcp_internal_annotations_test.go @@ -1,6 +1,7 @@ package server import ( + "strings" "testing" "github.com/mark3labs/mcp-go/mcp" @@ -85,6 +86,22 @@ func TestCallToolVariantAnnotations(t *testing.T) { } } +func TestCallToolVariantDescriptionsHonorRouteAnnotations(t *testing.T) { + for _, variant := range []string{ + contracts.ToolVariantRead, + contracts.ToolVariantWrite, + contracts.ToolVariantDestructive, + } { + description := buildCallToolVariantTool(variant).Description + assert.Contains(t, description, "call_with="+variant) + assert.Contains(t, description, "upstream annotations") + assert.Contains(t, description, "describe_tool") + assert.Contains(t, description, "requested outcome") + assert.NotContains(t, strings.ToLower(description), "default choice when unsure") + assert.NotContains(t, strings.ToLower(description), "decision rule") + } +} + // TestBuildManagementToolsAnnotations verifies the management tool set // (upstream_servers, quarantine_security, search_servers, list_registries) // have explicit annotation hints. These are shared across all routing modes. diff --git a/internal/server/mcp_routing_test.go b/internal/server/mcp_routing_test.go index c24f04881..a0c83d159 100644 --- a/internal/server/mcp_routing_test.go +++ b/internal/server/mcp_routing_test.go @@ -756,18 +756,14 @@ func TestRetrieveToolsInstructions_CodeExecutionMode(t *testing.T) { assert.Contains(t, instructions, "call_tool(", "code_execution mode should mention call_tool() JavaScript function") - // Code execution mode: should NOT recommend call_tool_read/write/destructive as tools to use. - // Note: the instructions may mention them in a "Do NOT use" warning, which is acceptable. - // What they must NOT contain is the retrieve_tools-mode decision rules that tell the LLM - // to use these as tool variants. - assert.NotContains(t, instructions, "DECISION RULES BY TOOL NAME", - "code_execution mode should NOT contain call_tool variant decision rules") - assert.NotContains(t, instructions, "(1) READ (call_tool_read)", - "code_execution mode should NOT recommend call_tool_read as a variant") - assert.NotContains(t, instructions, "(2) WRITE (call_tool_write)", - "code_execution mode should NOT recommend call_tool_write as a variant") - assert.NotContains(t, instructions, "(3) DESTRUCTIVE (call_tool_destructive)", - "code_execution mode should NOT recommend call_tool_destructive as a variant") + // Code execution mode: should NOT carry the retrieve_tools-mode selection + // guide that tells the LLM to pick a call_tool_* variant. The guide's + // heading is asserted present in retrieve_tools mode below, so this check + // cannot pass vacuously if the wording moves again. + assert.NotContains(t, instructions, "TOOL SELECTION GUIDE", + "code_execution mode should NOT contain the call_tool variant selection guide") + assert.NotContains(t, instructions, "'call_with' value as the exact variant to call", + "code_execution mode should NOT tell the LLM to call a call_tool_* variant") } // TestRetrieveToolsInstructions_RetrieveToolsMode verifies that handleRetrieveToolsWithMode @@ -795,6 +791,11 @@ func TestRetrieveToolsInstructions_RetrieveToolsMode(t *testing.T) { instructions, ok := response["usage_instructions"].(string) require.True(t, ok, "usage_instructions should be a string") + // Retrieve tools mode: carries the variant selection guide (the same + // heading TestRetrieveToolsInstructions_CodeExecutionMode asserts absent, + // so neither check can pass vacuously if the wording moves). + assert.Contains(t, instructions, "TOOL SELECTION GUIDE", + "retrieve_tools mode should carry the call_tool variant selection guide") // Retrieve tools mode: should mention call_tool_read/write/destructive assert.Contains(t, instructions, "call_tool_read", "retrieve_tools mode should mention call_tool_read") @@ -804,6 +805,9 @@ func TestRetrieveToolsInstructions_RetrieveToolsMode(t *testing.T) { "retrieve_tools mode should mention call_tool_destructive") assert.Contains(t, instructions, "INTENT TRACKING", "retrieve_tools mode should mention intent tracking") + assert.Contains(t, instructions, "upstream annotations") + assert.Contains(t, instructions, "existing read fallback") + assert.NotContains(t, instructions, "DECISION RULES BY TOOL NAME") } // TestRetrieveToolsInstructions_DefaultMode verifies that handleRetrieveToolsWithMode diff --git a/internal/server/retrieve_tools_profile_v3_golden_test.go b/internal/server/retrieve_tools_profile_v3_golden_test.go index 6fe3bd931..405b95000 100644 --- a/internal/server/retrieve_tools_profile_v3_golden_test.go +++ b/internal/server/retrieve_tools_profile_v3_golden_test.go @@ -8,10 +8,10 @@ import ( "github.com/stretchr/testify/require" ) -// Spec 108 (Profiles v3) T021: the one new golden this PR adds -// (contracts/mcp-tools.md "Frozen goldens"). Legacy goldens -// (retrieve_full_default.golden.json etc.) are untouched (SC-003) — this -// file adds a NEW golden for the NEW non-legacy response shape only. +// Spec 108 (Profiles v3) T021: profile-surface golden for the new response +// shape (contracts/mcp-tools.md "Frozen goldens"). This golden is refreshed +// alongside the other retrieve_tools response goldens when the compact +// routing guidance changes. // Regenerate with: UPDATE_GOLDEN=1 go test ./internal/server -run // TestRetrieveToolsProfileV3_GoldenByteIdentity func TestRetrieveToolsProfileV3_GoldenByteIdentity(t *testing.T) { diff --git a/internal/server/testdata/retrieve_full_default.golden.json b/internal/server/testdata/retrieve_full_default.golden.json index ab4d625fc..fb9819d9b 100644 --- a/internal/server/testdata/retrieve_full_default.golden.json +++ b/internal/server/testdata/retrieve_full_default.golden.json @@ -1 +1 @@ -{"query":"manage","tools":[{"call_with":"call_tool_read","description":"Get repository metadata to manage projects.","inputSchema":{"properties":{},"type":"object"},"name":"github:get_repo","score":0.011312138508548623,"server":"github"},{"call_with":"call_tool_read","description":"List issues to manage a repository backlog.","inputSchema":{"properties":{"repo":{"type":"string"},"state":{"enum":["open","closed","all"]}},"required":["repo"],"type":"object"},"name":"github:list_issues","score":0.008243798662285959,"server":"github"},{"call_with":"call_tool_read","description":"Search cities to manage location lookups across regions worldwide.","inputSchema":{"properties":{"id":{"type":["string","integer"]},"q":{"type":"string"}},"required":["q"],"type":"object"},"name":"weather:search_city","score":0.007666460133457465,"server":"weather"},{"call_with":"call_tool_read","description":"Get a weather forecast to manage travel plans.","inputSchema":{"properties":{"days":{"type":"integer"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"type":"object"}},"required":["location"],"type":"object"},"name":"weather:get_forecast","score":0.007056919206727505,"server":"weather"},{"call_with":"call_tool_read","description":"Create an issue to manage work. Supports labels and assignees.","inputSchema":{"properties":{"body":{"type":"string"},"labels":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"ttl":{"default":3600,"type":"integer"}},"required":["title"],"type":"object"},"name":"github:create_issue","score":0.00646672399372599,"server":"github"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"query":"manage","tools":[{"call_with":"call_tool_read","description":"Get repository metadata to manage projects.","inputSchema":{"properties":{},"type":"object"},"name":"github:get_repo","score":0.011312138508548623,"server":"github"},{"call_with":"call_tool_read","description":"List issues to manage a repository backlog.","inputSchema":{"properties":{"repo":{"type":"string"},"state":{"enum":["open","closed","all"]}},"required":["repo"],"type":"object"},"name":"github:list_issues","score":0.008243798662285959,"server":"github"},{"call_with":"call_tool_read","description":"Search cities to manage location lookups across regions worldwide.","inputSchema":{"properties":{"id":{"type":["string","integer"]},"q":{"type":"string"}},"required":["q"],"type":"object"},"name":"weather:search_city","score":0.007666460133457465,"server":"weather"},{"call_with":"call_tool_read","description":"Get a weather forecast to manage travel plans.","inputSchema":{"properties":{"days":{"type":"integer"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"type":"object"}},"required":["location"],"type":"object"},"name":"weather:get_forecast","score":0.007056919206727505,"server":"weather"},{"call_with":"call_tool_read","description":"Create an issue to manage work. Supports labels and assignees.","inputSchema":{"properties":{"body":{"type":"string"},"labels":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"ttl":{"default":3600,"type":"integer"}},"required":["title"],"type":"object"},"name":"github:create_issue","score":0.00646672399372599,"server":"github"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/retrieve_full_stats.golden.json b/internal/server/testdata/retrieve_full_stats.golden.json index afac70bfd..f71a0283e 100644 --- a/internal/server/testdata/retrieve_full_stats.golden.json +++ b/internal/server/testdata/retrieve_full_stats.golden.json @@ -1 +1 @@ -{"query":"manage","tools":[{"call_with":"call_tool_read","description":"Get repository metadata to manage projects.","inputSchema":{"properties":{},"type":"object"},"name":"github:get_repo","score":0.011312138508548623,"server":"github"},{"call_with":"call_tool_read","description":"List issues to manage a repository backlog.","inputSchema":{"properties":{"repo":{"type":"string"},"state":{"enum":["open","closed","all"]}},"required":["repo"],"type":"object"},"name":"github:list_issues","score":0.008243798662285959,"server":"github"},{"call_with":"call_tool_read","description":"Search cities to manage location lookups across regions worldwide.","inputSchema":{"properties":{"id":{"type":["string","integer"]},"q":{"type":"string"}},"required":["q"],"type":"object"},"name":"weather:search_city","score":0.007666460133457465,"server":"weather"},{"call_with":"call_tool_read","description":"Get a weather forecast to manage travel plans.","inputSchema":{"properties":{"days":{"type":"integer"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"type":"object"}},"required":["location"],"type":"object"},"name":"weather:get_forecast","score":0.007056919206727505,"server":"weather"},{"call_with":"call_tool_read","description":"Create an issue to manage work. Supports labels and assignees.","inputSchema":{"properties":{"body":{"type":"string"},"labels":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"ttl":{"default":3600,"type":"integer"}},"required":["title"],"type":"object"},"name":"github:create_issue","score":0.00646672399372599,"server":"github"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing.","usage_summary":{"top_tools":[]}} +{"query":"manage","tools":[{"call_with":"call_tool_read","description":"Get repository metadata to manage projects.","inputSchema":{"properties":{},"type":"object"},"name":"github:get_repo","score":0.011312138508548623,"server":"github"},{"call_with":"call_tool_read","description":"List issues to manage a repository backlog.","inputSchema":{"properties":{"repo":{"type":"string"},"state":{"enum":["open","closed","all"]}},"required":["repo"],"type":"object"},"name":"github:list_issues","score":0.008243798662285959,"server":"github"},{"call_with":"call_tool_read","description":"Search cities to manage location lookups across regions worldwide.","inputSchema":{"properties":{"id":{"type":["string","integer"]},"q":{"type":"string"}},"required":["q"],"type":"object"},"name":"weather:search_city","score":0.007666460133457465,"server":"weather"},{"call_with":"call_tool_read","description":"Get a weather forecast to manage travel plans.","inputSchema":{"properties":{"days":{"type":"integer"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"type":"object"}},"required":["location"],"type":"object"},"name":"weather:get_forecast","score":0.007056919206727505,"server":"weather"},{"call_with":"call_tool_read","description":"Create an issue to manage work. Supports labels and assignees.","inputSchema":{"properties":{"body":{"type":"string"},"labels":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"ttl":{"default":3600,"type":"integer"}},"required":["title"],"type":"object"},"name":"github:create_issue","score":0.00646672399372599,"server":"github"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing.","usage_summary":{"top_tools":[]}} diff --git a/internal/server/testdata/retrieve_tools_profile_v3.golden.json b/internal/server/testdata/retrieve_tools_profile_v3.golden.json index fe3178389..8623d97da 100644 --- a/internal/server/testdata/retrieve_tools_profile_v3.golden.json +++ b/internal/server/testdata/retrieve_tools_profile_v3.golden.json @@ -1 +1 @@ -{"hidden_by_profile":0,"profile":"work-readonly","query":"list_issues","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"readOnlyHint":true},"call_with":"call_tool_read","description":"list_issues","inputSchema":{},"name":"github:list_issues","score":2.575623641485255,"server":"github"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"hidden_by_profile":0,"profile":"work-readonly","query":"list_issues","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"readOnlyHint":true},"call_with":"call_tool_read","description":"list_issues","inputSchema":{},"name":"github:list_issues","score":2.575623641485255,"server":"github"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/spec094/a_no_filters_compact.golden.json b/internal/server/testdata/spec094/a_no_filters_compact.golden.json index 9b39a577d..92a288865 100644 --- a/internal/server/testdata/spec094/a_no_filters_compact.golden.json +++ b/internal/server/testdata/spec094/a_no_filters_compact.golden.json @@ -1 +1 @@ -{"hint":"sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Before calling a tool whose entry is lossy:true, call describe_tool with its id to get the full input schema.","query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"desc":"widgetquery purge item","id":"annot:purge_item","lossy":false,"score":0.013467029455043762,"sig":"()"},{"desc":"widgetquery reach web","id":"annot:reach_web","lossy":false,"score":0.013467029455043762,"sig":"()"},{"desc":"widgetquery safeonlyterm listing","id":"annot:safe_read","lossy":false,"score":0.013467029455043762,"sig":"()"},{"desc":"widgetquery write item","id":"annot:write_item","lossy":false,"score":0.013467029455043762,"sig":"()"},{"desc":"widgetquery mystery tool","id":"plain:mystery_tool","lossy":false,"score":0.013467029455043762,"sig":"()"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"hint":"sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Follow the call_with route exactly; it matches the full tool result, including the existing read fallback when no tier annotations are available. Never infer a route from the name, description, command text, or requested outcome. Before calling a lossy entry, call describe_tool for its full input schema.","query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"call_with":"call_tool_destructive","desc":"widgetquery purge item","id":"annot:purge_item","lossy":false,"score":0.013467029455043762,"sig":"()"},{"call_with":"call_tool_read","desc":"widgetquery reach web","id":"annot:reach_web","lossy":false,"score":0.013467029455043762,"sig":"()"},{"call_with":"call_tool_read","desc":"widgetquery safeonlyterm listing","id":"annot:safe_read","lossy":false,"score":0.013467029455043762,"sig":"()"},{"call_with":"call_tool_write","desc":"widgetquery write item","id":"annot:write_item","lossy":false,"score":0.013467029455043762,"sig":"()"},{"call_with":"call_tool_read","desc":"widgetquery mystery tool","id":"plain:mystery_tool","lossy":false,"score":0.013467029455043762,"sig":"()"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/spec094/a_no_filters_full.golden.json b/internal/server/testdata/spec094/a_no_filters_full.golden.json index b7e3ad1fa..a4223417f 100644 --- a/internal/server/testdata/spec094/a_no_filters_full.golden.json +++ b/internal/server/testdata/spec094/a_no_filters_full.golden.json @@ -1 +1 @@ -{"query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"destructiveHint":true,"openWorldHint":false},"call_with":"call_tool_destructive","description":"widgetquery purge item","inputSchema":{"type":"object"},"name":"annot:purge_item","score":0.013467029455043762,"server":"annot"},{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":true},"call_with":"call_tool_read","description":"widgetquery reach web","inputSchema":{"type":"object"},"name":"annot:reach_web","score":0.013467029455043762,"server":"annot"},{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_read","description":"widgetquery safeonlyterm listing","inputSchema":{"type":"object"},"name":"annot:safe_read","score":0.013467029455043762,"server":"annot"},{"annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_write","description":"widgetquery write item","inputSchema":{"type":"object"},"name":"annot:write_item","score":0.013467029455043762,"server":"annot"},{"call_with":"call_tool_read","description":"widgetquery mystery tool","inputSchema":{"type":"object"},"name":"plain:mystery_tool","score":0.013467029455043762,"server":"plain"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"destructiveHint":true,"openWorldHint":false},"call_with":"call_tool_destructive","description":"widgetquery purge item","inputSchema":{"type":"object"},"name":"annot:purge_item","score":0.013467029455043762,"server":"annot"},{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":true},"call_with":"call_tool_read","description":"widgetquery reach web","inputSchema":{"type":"object"},"name":"annot:reach_web","score":0.013467029455043762,"server":"annot"},{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_read","description":"widgetquery safeonlyterm listing","inputSchema":{"type":"object"},"name":"annot:safe_read","score":0.013467029455043762,"server":"annot"},{"annotations":{"readOnlyHint":false,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_write","description":"widgetquery write item","inputSchema":{"type":"object"},"name":"annot:write_item","score":0.013467029455043762,"server":"annot"},{"call_with":"call_tool_read","description":"widgetquery mystery tool","inputSchema":{"type":"object"},"name":"plain:mystery_tool","score":0.013467029455043762,"server":"plain"}],"total":5,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/spec094/b_zero_omissions_compact.golden.json b/internal/server/testdata/spec094/b_zero_omissions_compact.golden.json index 1b391e6fa..740a65f97 100644 --- a/internal/server/testdata/spec094/b_zero_omissions_compact.golden.json +++ b/internal/server/testdata/spec094/b_zero_omissions_compact.golden.json @@ -1 +1 @@ -{"hint":"sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Before calling a tool whose entry is lossy:true, call describe_tool with its id to get the full input schema.","query":"safeonlyterm","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"desc":"widgetquery safeonlyterm listing","id":"annot:safe_read","lossy":false,"score":0.07293390164320027,"sig":"()"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"hint":"sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Follow the call_with route exactly; it matches the full tool result, including the existing read fallback when no tier annotations are available. Never infer a route from the name, description, command text, or requested outcome. Before calling a lossy entry, call describe_tool for its full input schema.","query":"safeonlyterm","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"call_with":"call_tool_read","desc":"widgetquery safeonlyterm listing","id":"annot:safe_read","lossy":false,"score":0.07293390164320027,"sig":"()"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/spec094/b_zero_omissions_full.golden.json b/internal/server/testdata/spec094/b_zero_omissions_full.golden.json index 4cf8faf35..20504d021 100644 --- a/internal/server/testdata/spec094/b_zero_omissions_full.golden.json +++ b/internal/server/testdata/spec094/b_zero_omissions_full.golden.json @@ -1 +1 @@ -{"query":"safeonlyterm","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_read","description":"widgetquery safeonlyterm listing","inputSchema":{"type":"object"},"name":"annot:safe_read","score":0.07293390164320027,"server":"annot"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"query":"safeonlyterm","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_read","description":"widgetquery safeonlyterm listing","inputSchema":{"type":"object"},"name":"annot:safe_read","score":0.07293390164320027,"server":"annot"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/spec094/c_with_omissions_compact.golden.json b/internal/server/testdata/spec094/c_with_omissions_compact.golden.json index 1a425382e..03c19f19a 100644 --- a/internal/server/testdata/spec094/c_with_omissions_compact.golden.json +++ b/internal/server/testdata/spec094/c_with_omissions_compact.golden.json @@ -1 +1 @@ -{"hint":"sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Before calling a tool whose entry is lossy:true, call describe_tool with its id to get the full input schema.","query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"desc":"widgetquery safeonlyterm listing","id":"annot:safe_read","lossy":false,"score":0.013467029455043762,"sig":"()"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"hint":"sig legend: name*:type = required param, ~ = collapsed/lossy (details omitted), (~) = schema unavailable. Follow the call_with route exactly; it matches the full tool result, including the existing read fallback when no tier annotations are available. Never infer a route from the name, description, command text, or requested outcome. Before calling a lossy entry, call describe_tool for its full input schema.","query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"call_with":"call_tool_read","desc":"widgetquery safeonlyterm listing","id":"annot:safe_read","lossy":false,"score":0.013467029455043762,"sig":"()"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/spec094/c_with_omissions_full.golden.json b/internal/server/testdata/spec094/c_with_omissions_full.golden.json index d4ab5fb63..d18394da9 100644 --- a/internal/server/testdata/spec094/c_with_omissions_full.golden.json +++ b/internal/server/testdata/spec094/c_with_omissions_full.golden.json @@ -1 +1 @@ -{"query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_read","description":"widgetquery safeonlyterm listing","inputSchema":{"type":"object"},"name":"annot:safe_read","score":0.013467029455043762,"server":"annot"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Check the 'call_with' field for each tool, then use the matching tool variant. DECISION RULES BY TOOL NAME: (1) READ (call_tool_read): search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. DEFAULT choice when unsure. (2) WRITE (call_tool_write): create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. (3) DESTRUCTIVE (call_tool_destructive): delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} +{"query":"widgetquery","session_risk":{"has_destructive_tools":true,"has_open_world_tools":true,"has_write_tools":true,"lethal_trifecta":true,"level":"high"},"tools":[{"annotations":{"readOnlyHint":true,"destructiveHint":false,"openWorldHint":false},"call_with":"call_tool_read","description":"widgetquery safeonlyterm listing","inputSchema":{"type":"object"},"name":"annot:safe_read","score":0.013467029455043762,"server":"annot"}],"total":1,"usage_instructions":"TOOL SELECTION GUIDE: Use each result's 'call_with' value as the exact variant to call (call_tool_read, call_tool_write, or call_tool_destructive). The route comes from upstream annotations and overrides tool names, descriptions, command wording, and apparent user intent. When no upstream tier annotations exist, call_with preserves the existing read fallback; do not infer a different route from tool names or intent. INTENT TRACKING: Always provide intent_reason (why you're calling this tool) and intent_data_sensitivity (public/internal/private/unknown) to enable activity auditing."} diff --git a/internal/server/testdata/toolslist_goldens/default_server.json b/internal/server/testdata/toolslist_goldens/default_server.json index d0fc5c93a..46d039336 100644 --- a/internal/server/testdata/toolslist_goldens/default_server.json +++ b/internal/server/testdata/toolslist_goldens/default_server.json @@ -7,7 +7,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a DESTRUCTIVE tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. Examples: delete_repo, remove_user, drop_table, revoke_access, clear_cache, terminate_session. Use for irreversible or high-impact operations. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a DESTRUCTIVE tool. Use this variant only when retrieve_tools returns call_with=call_tool_destructive. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. This variant does not bypass authorization, quarantine, approval, or other dispatch gates. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -47,7 +47,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a READ-ONLY tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. Examples: search_files, get_user, list_repositories, query_database, find_issues, check_status. This is the DEFAULT choice when unsure - most tools are read-only. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a READ-ONLY tool. Use this variant only when retrieve_tools returns call_with=call_tool_read. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -87,7 +87,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a STATE-MODIFYING tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. Examples: create_issue, update_file, send_message, add_comment, set_status, edit_page. Use only when explicitly modifying state. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a STATE-MODIFYING tool. Use this variant only when retrieve_tools returns call_with=call_tool_write. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -583,7 +583,7 @@ "idempotentHint": false, "openWorldHint": false }, - "description": "🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Results include 'annotations' (tool behavior hints like destructiveHint) and 'call_with' recommendation indicating which tool variant to use (call_tool_read/write/destructive). Then use the recommended variant with an 'intent' parameter. Compact mode returns one-line signatures ('sig': '*'=required, '~'=lossy) with first-sentence 'desc'; call describe_tool for full schemas. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers. Upstream servers' tools are reachable ONLY through this tool — search here before using a shell CLI (gh, aws, kubectl, curl) or a raw HTTP API for an external service. ANNOTATION FILTERS: read_only_only, exclude_destructive and exclude_open_world self-restrict discovery. When they withhold tools that matched your query, the response carries a 'filter_diagnostics' block with per-filter counts (split into missing upstream annotations vs. explicitly unsafe ones) and one suggestion; it is absent when nothing was withheld. Filter diagnostics describe this call's candidate window, not the whole catalog.", + "description": "🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Follow each result's call_with route exactly; upstream annotations determine that route and take precedence over tool names, descriptions, command text, and requested outcome. Compact results preserve the same call_with route as full results, including the existing read fallback when upstream tier annotations are unavailable. Never infer a route from a tool's name or intent. Compact mode returns one-line signatures ('sig': '*'=required, '~'=lossy) with first-sentence 'desc'; call describe_tool for full schemas. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers. Upstream servers' tools are reachable ONLY through this tool — search here before using a shell CLI (gh, aws, kubectl, curl) or a raw HTTP API for an external service. ANNOTATION FILTERS: read_only_only, exclude_destructive and exclude_open_world self-restrict discovery. When they withhold tools that matched your query, the response carries a 'filter_diagnostics' block with per-filter counts (split into missing upstream annotations vs. explicitly unsafe ones) and one suggestion; it is absent when nothing was withheld. Filter diagnostics describe this call's candidate window, not the whole catalog.", "inputSchema": { "properties": { "debug": { diff --git a/internal/server/testdata/toolslist_goldens/default_server_read_only.json b/internal/server/testdata/toolslist_goldens/default_server_read_only.json index 49249cfb7..2d00b7e6b 100644 --- a/internal/server/testdata/toolslist_goldens/default_server_read_only.json +++ b/internal/server/testdata/toolslist_goldens/default_server_read_only.json @@ -7,7 +7,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a DESTRUCTIVE tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. Examples: delete_repo, remove_user, drop_table, revoke_access, clear_cache, terminate_session. Use for irreversible or high-impact operations. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a DESTRUCTIVE tool. Use this variant only when retrieve_tools returns call_with=call_tool_destructive. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. This variant does not bypass authorization, quarantine, approval, or other dispatch gates. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -47,7 +47,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a READ-ONLY tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. Examples: search_files, get_user, list_repositories, query_database, find_issues, check_status. This is the DEFAULT choice when unsure - most tools are read-only. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a READ-ONLY tool. Use this variant only when retrieve_tools returns call_with=call_tool_read. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -87,7 +87,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a STATE-MODIFYING tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. Examples: create_issue, update_file, send_message, add_comment, set_status, edit_page. Use only when explicitly modifying state. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a STATE-MODIFYING tool. Use this variant only when retrieve_tools returns call_with=call_tool_write. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -515,7 +515,7 @@ "idempotentHint": false, "openWorldHint": false }, - "description": "🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Results include 'annotations' (tool behavior hints like destructiveHint) and 'call_with' recommendation indicating which tool variant to use (call_tool_read/write/destructive). Then use the recommended variant with an 'intent' parameter. Compact mode returns one-line signatures ('sig': '*'=required, '~'=lossy) with first-sentence 'desc'; call describe_tool for full schemas. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers. Upstream servers' tools are reachable ONLY through this tool — search here before using a shell CLI (gh, aws, kubectl, curl) or a raw HTTP API for an external service. ANNOTATION FILTERS: read_only_only, exclude_destructive and exclude_open_world self-restrict discovery. When they withhold tools that matched your query, the response carries a 'filter_diagnostics' block with per-filter counts (split into missing upstream annotations vs. explicitly unsafe ones) and one suggestion; it is absent when nothing was withheld. Filter diagnostics describe this call's candidate window, not the whole catalog.", + "description": "🔍 CALL THIS FIRST to discover relevant tools! This is the primary tool discovery mechanism that searches across ALL upstream MCP servers using intelligent BM25 full-text search. Always use this before attempting to call any specific tools. Use natural language to describe what you want to accomplish (e.g., 'create GitHub repository', 'query database', 'weather forecast'). Follow each result's call_with route exactly; upstream annotations determine that route and take precedence over tool names, descriptions, command text, and requested outcome. Compact results preserve the same call_with route as full results, including the existing read fallback when upstream tier annotations are unavailable. Never infer a route from a tool's name or intent. Compact mode returns one-line signatures ('sig': '*'=required, '~'=lossy) with first-sentence 'desc'; call describe_tool for full schemas. NOTE: Quarantined servers are excluded from search results for security. Use 'quarantine_security' tool to examine and manage quarantined servers. TO ADD NEW SERVERS: Use 'list_registries' then 'search_servers' to find and add new MCP servers. Upstream servers' tools are reachable ONLY through this tool — search here before using a shell CLI (gh, aws, kubectl, curl) or a raw HTTP API for an external service. ANNOTATION FILTERS: read_only_only, exclude_destructive and exclude_open_world self-restrict discovery. When they withhold tools that matched your query, the response carries a 'filter_diagnostics' block with per-filter counts (split into missing upstream annotations vs. explicitly unsafe ones) and one suggestion; it is absent when nothing was withheld. Filter diagnostics describe this call's candidate window, not the whole catalog.", "inputSchema": { "properties": { "debug": { diff --git a/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json b/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json index e62435964..0f1a65d7e 100644 --- a/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json +++ b/internal/server/testdata/toolslist_goldens/retrieve_tools_mode.json @@ -7,7 +7,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a DESTRUCTIVE tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: delete, remove, drop, revoke, disable, destroy, purge, reset, clear, unsubscribe, cancel, terminate, close, archive, ban, block, disconnect, kill, wipe, truncate, force, hard. Examples: delete_repo, remove_user, drop_table, revoke_access, clear_cache, terminate_session. Use for irreversible or high-impact operations. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a DESTRUCTIVE tool. Use this variant only when retrieve_tools returns call_with=call_tool_destructive. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. This variant does not bypass authorization, quarantine, approval, or other dispatch gates. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -47,7 +47,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a READ-ONLY tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: search, query, list, get, fetch, find, check, view, read, show, describe, lookup, retrieve, browse, explore, discover, scan, inspect, analyze, examine, validate, verify. Examples: search_files, get_user, list_repositories, query_database, find_issues, check_status. This is the DEFAULT choice when unsure - most tools are read-only. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a READ-ONLY tool. Use this variant only when retrieve_tools returns call_with=call_tool_read. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { @@ -87,7 +87,7 @@ "idempotentHint": false, "openWorldHint": true }, - "description": "Execute a STATE-MODIFYING tool. WORKFLOW: 1) Call retrieve_tools first to find tools, 2) Use the exact 'name' field from results, 3) Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). DECISION RULE: Use this when the tool name contains: create, update, modify, add, set, send, edit, change, write, post, put, patch, insert, upload, submit, assign, configure, enable, register, subscribe, publish, move, copy, rename, merge. Examples: create_issue, update_file, send_message, add_comment, set_status, edit_page. Use only when explicitly modifying state. Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", + "description": "Execute a STATE-MODIFYING tool. Use this variant only when retrieve_tools returns call_with=call_tool_write. The upstream annotations and call_with are authoritative over a tool's name, description, command text, or the requested outcome. Build args from the 'sig' signature ('*'=required; if lossy '~', call describe_tool first). Result blocks may be prefixed by the marker line: [mcpproxy:toon/v1] TOON-encoded JSON (toon-format.org); decode to JSON before reuse - tool arguments must still be sent as JSON.", "inputSchema": { "properties": { "args": { diff --git a/internal/server/toolslist_snapshot_test.go b/internal/server/toolslist_snapshot_test.go index 9f49a30ae..2362ea3a8 100644 --- a/internal/server/toolslist_snapshot_test.go +++ b/internal/server/toolslist_snapshot_test.go @@ -14,15 +14,16 @@ import ( ) // Spec 098 (required-tools preflight) T002/T024 — FR-015: the preflight -// feature adds a REST endpoint and a CLI command; it MUST NOT move the MCP -// surface. `tools/list` payloads have to stay byte-identical to the merge-base -// release across every routing mode an agent can be served. +// feature adds a REST endpoint and a CLI command; it MUST NOT make an +// unenumerated change to the MCP surface. `tools/list` payloads stay +// byte-identical to their current goldens across every routing mode, and the +// delta from the frozen baseline is checked field by field below. // -// The goldens in testdata/toolslist_goldens/ were captured from the merge-base -// commit (bfd43e7ce, origin/main, pre-098) with this exact test file — copied -// into a throwaway `git worktree` of origin/main and run with -// MCPPROXY_WRITE_TOOLSLIST_GOLDENS set — so the capture and the comparison -// share one serializer and cannot drift. +// The frozen goldens in testdata/toolslist_goldens/pre099/ were captured from +// the merge-base commit (bfd43e7ce, origin/main, pre-098) with this test file. +// The current surface goldens are generated by the same serializer and pin +// the enumerated changes, including compact routing guidance on retrieve_tools +// and call_tool_*; their historical pre099/pre105 baselines remain unchanged. // // SPEC 099 (FR-014/FR-015) converted this from a NO-delta gate into an // ENUMERATED-delta gate — the spec-085/094 pattern in mcp_menu_surface_test.go @@ -210,6 +211,11 @@ func TestToolsListSnapshot_MatchesMergeBaseGoldens(t *testing.T) { // clients read the empty properties map as "no keys allowed". Schema shape // of that one parameter only; assertCallToolVariantDelta and // TestOpenObjectParamsAreNotGrammarClosed_Issue1364 pin it. +// - retrieve_tools and call_tool_* — compact routing guidance: call_with is +// now preserved in compact results, and the descriptions direct agents to +// follow that authoritative route instead of classifying by tool name. +// Their current serialized definitions are pinned by the live goldens and +// TestCallToolVariantDescriptionsHonorRouteAnnotations. // - retrieve_tools — agent visibility: the description states that upstream // tools are reachable ONLY through it, so agents search before falling // back to shell CLIs (retrieveToolsReachNote). DESCRIPTION ONLY, static @@ -356,11 +362,11 @@ func reportToolsListDiff(t *testing.T, surface string, want, got []byte) { // The code_execution definition told every caller to discover stored scripts // by requesting a name that does not exist. Under FR-012 that enumeration is // administrator-only (an agent-token caller gets a non-disclosing refusal, -// see mcp_code_scripts_test.go), so the published text has to say so — and -// the goldens that pin the text move by exactly those two strings and -// nothing else. testdata/toolslist_goldens/pre105/ is the FROZEN copy of the -// three goldens as they stood before this spec (never regenerated); the live -// goldens are compared against it entry by entry and field by field. +// see mcp_code_scripts_test.go), so the published text has to say so. The +// frozen pre-105 comparison also permits the later compact-routing guidance +// changes to retrieve_tools and call_tool_* descriptions, while checking their +// route text separately and comparing their schemas after the #1364 change. +// testdata/toolslist_goldens/pre105/ remains the FROZEN baseline. // --------------------------------------------------------------------------- const ( @@ -384,6 +390,16 @@ const ( // assertListRegistriesDelta. var spec109CatalogTools = map[string]bool{"search_servers": true, "list_registries": true} +// pre105RetrieveToolsRoutingSentence is the routing sentence the frozen +// pre-105 retrieve_tools description carried; compactRoutingGuidanceSentence +// is what #1668 put in its place. Both are test-owned so the exact-delta +// assertion in TestCodeExecutionDescriptions_EnumerationIsAdminOnly cannot be +// satisfied by whatever the production literal happens to say. +const ( + pre105RetrieveToolsRoutingSentence = "Results include 'annotations' (tool behavior hints like destructiveHint) and 'call_with' recommendation indicating which tool variant to use (call_tool_read/write/destructive). Then use the recommended variant with an 'intent' parameter. " + compactRoutingGuidanceSentence = "Follow each result's call_with route exactly; upstream annotations determine that route and take precedence over tool names, descriptions, command text, and requested outcome. Compact results preserve the same call_with route as full results, including the existing read fallback when upstream tier annotations are unavailable. Never infer a route from a tool's name or intent. " +) + // spec105EnumerationPhrases are the pre-105 fragments that advertised // discovery-by-failed-call. Neither may survive in the live strings. var spec105EnumerationPhrases = []string{ @@ -456,34 +472,75 @@ func TestCodeExecutionDescriptions_EnumerationIsAdminOnly(t *testing.T) { continue } if name == "retrieve_tools" { - // Agent visibility: the description gained exactly - // retrieveToolsReachNote. With it removed the entry must - // still equal the frozen pre-105 capture. + // Agent visibility and compact routing guidance are both + // deliberate description changes. Pin the new route policy, + // then normalize only this description to compare the rest of + // the entry with the frozen capture. var postM map[string]interface{} + var preM map[string]interface{} + require.NoError(t, json.Unmarshal(pre, &preM)) require.NoError(t, json.Unmarshal(after[name], &postM)) desc, _ := postM["description"].(string) assert.Contains(t, desc, retrieveToolsReachNote, "surface %s: retrieve_tools carries the reach note", surface) - postM["description"] = strings.Replace(desc, retrieveToolsReachNote, "", 1) + if surface != "default_server" { + postM["description"] = strings.Replace(desc, retrieveToolsReachNote, "", 1) + } else { + // Exact delta (#1668): the pre-105 routing sentence is + // replaced by the compact-routing guidance, and the reach + // note sits in front of the diagnostics note the frozen + // capture already carried. Nothing else in the + // description may move; both sentences are test-owned + // so a drift in the production literal fails here. + preDesc, _ := preM["description"].(string) + require.Contains(t, preDesc, pre105RetrieveToolsRoutingSentence, + "surface %s: frozen retrieve_tools description carries the pre-105 routing sentence", surface) + require.Contains(t, preDesc, retrieveToolsDiagnosticsNote, + "surface %s: frozen retrieve_tools description carries the diagnostics note", surface) + expected := strings.Replace(preDesc, pre105RetrieveToolsRoutingSentence, compactRoutingGuidanceSentence, 1) + expected = strings.Replace(expected, retrieveToolsDiagnosticsNote, retrieveToolsReachNote+retrieveToolsDiagnosticsNote, 1) + assert.Equal(t, expected, desc, + "surface %s: retrieve_tools description may differ from pre-105 only by the #1668 routing sentence and the two live notes", surface) + postM["description"] = preM["description"] + } trimmed, err := json.Marshal(postM) require.NoError(t, err) assert.JSONEq(t, string(pre), string(trimmed), - "surface %s: retrieve_tools may differ from the pre-105 golden only by retrieveToolsReachNote", surface) + "surface %s: retrieve_tools may differ from pre-105 only by the allowed description and existing schema deltas", surface) continue } if isCallToolVariantName(name) { - // Issue #1364: only args' open-object shape moved. + // Compact routing guidance changes the description; issue + // #1364 changes the args object shape. Pin route authority, + // then compare all remaining fields to the frozen capture. var postM map[string]interface{} + var preM map[string]interface{} + require.NoError(t, json.Unmarshal(pre, &preM)) require.NoError(t, json.Unmarshal(after[name], &postM)) + desc, _ := postM["description"].(string) + preDesc, _ := preM["description"].(string) + // Exact delta (#1668): the live description IS the builder + // text (which already carries the TOON marker note), and + // that note is byte-equal to the frozen capture's tail, so + // only the routing contract in front of it moved. + tailAt := strings.Index(preDesc, " Result blocks may be prefixed") + require.Greater(t, tailAt, 0, "surface %s: %s frozen description carries the result-marker tail", surface, name) + assert.Equal(t, buildCallToolVariantTool(name).Description, desc, + "surface %s: %s description equals the live routing contract exactly", surface, name) + assert.True(t, strings.HasSuffix(desc, preDesc[tailAt:]), + "surface %s: %s keeps the frozen result-marker tail byte for byte", surface, name) + assert.Contains(t, desc, "call_with="+name) + assert.Contains(t, desc, "authoritative over a tool's name") + postM["description"] = preM["description"] closeOpenObjects(t, postM, "args") trimmed, err := json.Marshal(postM) require.NoError(t, err) assert.JSONEq(t, string(pre), string(trimmed), - "surface %s: %s may differ from the pre-105 golden only by the #1364 open-object args shape", surface, name) + "surface %s: %s may differ from pre-105 only by route guidance and the #1364 open-object args shape", surface, name) continue } assert.True(t, bytes.Equal(pre, after[name]), - "surface %s: tool %q must be byte-identical to the pre-105 golden (FR-012: only code_execution may move)", surface, name) + "surface %s: tool %q must be byte-identical to the pre-105 golden outside enumerated deltas", surface, name) } preTool, ok := before[spec105CodeExecutionTool] diff --git a/specs/085-compact-router/data-model.md b/specs/085-compact-router/data-model.md index 5e9c59709..ca2bf2dcd 100644 --- a/specs/085-compact-router/data-model.md +++ b/specs/085-compact-router/data-model.md @@ -112,10 +112,14 @@ Produced by `buildToolEntry(result, mode, opts)` (new `internal/server/mcp_entry ```json { "id": "digitalocean:cdn_create", "score": 0.94, "lossy": false, "sig": "(origin*:str, ttl:int=3600, certificate_id:str)", - "desc": "Create a CDN for a Spaces bucket" } + "desc": "Create a CDN for a Spaces bucket", + "call_with": "call_tool_write" } ``` - `id` = `server:tool` (`result.Tool.ServerName` + `result.Tool.Name`, normalized to `server:tool` exactly as today's `name`). Ranking order preserved (SC-002). +- `call_with` preserves the same route as full mode, including the existing `call_tool_read` + fallback when upstream tier annotations are unavailable. Agents must follow this field instead + of inferring a route from tool names, descriptions, command text, or requested outcome. - No `inputSchema`, no `description` (full), no `annotations` block — those move to `describe_tool` / self-healing errors. - Compact response adds top-level `hint` (FR-009): a single deterministic line explaining the