Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/features/search-discovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 5 additions & 2 deletions internal/contracts/intent.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
17 changes: 7 additions & 10 deletions internal/server/mcp.go
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Expand All @@ -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."
Expand All @@ -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."
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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."
}

Expand Down
35 changes: 29 additions & 6 deletions internal/server/mcp_entry_builder.go
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
Loading
Loading