First-class tool names: (mcp.v1.tool_name) option + Gemini-safe mangling (#46)

* gen: force mangled tool names to start with a letter

Providers disagree on the leading character of a function name: Gemini
requires a letter or underscore, OpenAI and Anthropic also accept
digits. The base-36 hash prefix of a mangled name can start with a
digit, and Gemini then rejects the entire request with "Invalid
function name" -- a single over-long proto method bricks every
Gemini-backed agent using the server (live failure:
morningstar-securities GetEquityResearchReport, 2026-06-10).

Map a leading digit onto 'g'..'p'. Hashes already starting with a
letter are unchanged, so only the names that were broken on Gemini
change.

* gen: add (mcp.v1.tool_name) option for first-class tool names

Derived tool names are an encoding of proto full names, not names a
model should read: 40+ characters of package prefix, hash-truncated
when too long. This makes high-fidelity names a first-class feature:

    rpc GetEquityResearchReport(...) returns (...) {
      option (mcp.v1.tool_name) = "get_equity_research_report";
    }

The option affects only the MCP tool layer -- runtime.Tool.Name in
generated registration code and in dynamic RegisterService. Generated
Go identifiers stay proto-derived. Unset means the derived name,
exactly as before.

Guard rails:
- the value must match ^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$, the
  intersection of every provider's function-name rules; codegen fails
  on an invalid value.
- duplicate tool names fail codegen across the whole generation run
  (one ToolNameRegistry per plugin invocation). Derived names are
  unique by construction, so duplicates can only come from the option.
- the dynamic path falls back to the derived name on an invalid or
  colliding configured name: a gateway must keep serving, and derived
  names are always safe.

With MCPs declaring their own short names, consumers that prefix
tools (agent runtimes prefix "mcpname__") stop running into length
mangling, and models get names worth reading.

* gen: harden tool_name option per Codex review

- A configured name squatting on a later method's derived name made
  the dynamic-path fallback recompute that same derived name and call
  AddTool twice with it. The fallback now de-collides with a numeric
  suffix; AddTool is never called twice with one name.
- An explicitly authored (mcp.v1.tool_name) = "" was indistinguishable
  from an unset option and slipped past codegen validation.
  ConfiguredToolName now reports presence separately (HasExtension),
  so the generator rejects it.
- Tighten validation to lowercase: ^[a-z_][a-z0-9_-]{0,63}$. Derived
  and mangled names always contain an UpperCamel "<Service>Service_"
  segment, so a lowercase-only configured name can never be mistaken
  for one by downstream de-mangling heuristics (aigw's toolname.Short
  keys on exactly that segment) -- configured names provably pass
  through them untouched.

* gen: regenerate annotations.pb.go for the lowercase tool-name rule

The proto source comment was tightened to ^[a-z_][a-z0-9_-]{0,63}$
but the generated file still carried the old uppercase-permitting
doc -- the extension docs are the public API surface and must not
contradict the validator. Caught by review.

* gen: golden-test tool naming, scope dup guard per service

Add testdata/tool_naming.proto to the golden generation test, pinning
all three naming behaviors in emitted .pb.mcp.go output: a configured
(mcp.v1.tool_name) emitted verbatim ("get_dashboard"), a derived name
unchanged, and a >64-char name hash-truncated with a letter-leading
prefix. Existing goldens are byte-identical, proving the default path
did not move. The annotations proto is vendored into the testdata buf
module (buf modules cannot depend on local sibling dirs); its Go
output is suppressed so mcp/v1/annotations.proto registers exactly
once (pkg/mcpv1).

Re-scope the duplicate-name guard from per-run to per-service and
drop ToolNameRegistry. A plugin run's file set is not a deployment
unit: in a monorepo every MCP proto generates in one run, and two
different MCPs may legitimately both name a tool "get_dashboard" --
they never share a server. The only statically decidable collision is
within one service (one Register<Service>Handler call), which is
where the guard now lives.

Author: birdayz

README.md

@@ -162,6 +162,22 @@ sqlv1mcp.RegisterSQLServiceHandler(s, clickhouseHandler, runtime.WithNamePrefix(
 // Tools: postgres_SQLService_Query, clickhouse_SQLService_Query, ...
 ```
 
+### Tool naming
+
+By default a tool is named after the method's full proto name with dots replaced by underscores (`redpanda_mcps_sql_v1_SQLService_Query`). Names longer than 64 characters — the strictest provider limit — are truncated: a 10-character hash of the full name plus as much of the tail (the most specific part) as fits. The hash is forced to start with a letter because Gemini rejects function names that start with a digit.
+
+To publish a method under a stable, human-chosen name instead, set the `(mcp.v1.tool_name)` method option:
+
+```proto
+import "mcp/v1/annotations.proto";
+
+rpc GetEquityResearchReport(GetEquityResearchReportRequest) returns (GetEquityResearchReportResponse) {
+  option (mcp.v1.tool_name) = "get_equity_research_report";
+}
+```
+
+The value must match `^[a-z_][a-z0-9_-]{0,63}$` — lowercase snake/kebab case within every provider's function-name rules; lowercase guarantees configured names pass untouched through consumers' de-mangling heuristics (they key on the UpperCamel `Service_` segment of derived names). Code generation fails on an invalid value and on duplicate tool names within a service (one service is one MCP server registration — different services may legitimately reuse a name). The dynamic registration path (`gen.RegisterService`) applies the same option; an invalid or colliding configured name there falls back to the derived name so a tool is never silently dropped.
+
 ## Migrating from mark3labs-only (pre-v0.2)
 
 Generated code no longer imports `mark3labs/mcp-go` directly. It programs against the `runtime.MCPServer` interface, and you pick the MCP library via an adapter package.

justfile

@@ -39,9 +39,11 @@ update-build: gazelle
 
 # Generate proto code (outside Bazel)
 generate:
+    cd proto && buf generate
     cd pkg/testdata && buf generate buf.build/googleapis/googleapis
     cd pkg/testdata && buf generate --include-imports --exclude-path buf/validate
     rm -rf pkg/testdata/gen/go/buf/
+    rm -rf pkg/testdata/gen/go/mcp/
     cd pkg/testdata && buf build -o gen/descriptors.binpb --exclude-path buf/validate
     go run mvdan.cc/gofumpt@latest -l -w pkg/testdata/
 

pkg/gen/BUILD.bazel

@@ -5,16 +5,19 @@ go_library(
     srcs = [
         "register.go",
         "schema.go",
+        "toolname.go",
     ],
     importpath = "github.com/redpanda-data/protoc-gen-go-mcp/pkg/gen",
     visibility = ["//visibility:public"],
     deps = [
+        "//pkg/mcpv1",
         "//pkg/runtime",
         "@build_buf_gen_go_bufbuild_protovalidate_protocolbuffers_go//buf/validate",
         "@org_golang_google_genproto_googleapis_api//annotations",
         "@org_golang_google_protobuf//encoding/protojson",
         "@org_golang_google_protobuf//proto",
         "@org_golang_google_protobuf//reflect/protoreflect",
+        "@org_golang_google_protobuf//types/descriptorpb",
         "@org_golang_google_protobuf//types/dynamicpb",
     ],
 )
@@ -36,10 +39,12 @@ go_test(
         "schema_map_bug_test.go",
         "schema_recursive_test.go",
         "schema_test.go",
+        "toolname_test.go",
     ],
     data = glob(["testdata/**"]),
     embed = [":gen"],
     deps = [
+        "//pkg/mcpv1",
         "//pkg/runtime",
         "//pkg/runtime/mark3labs",
         "//pkg/testdata/gen/go/testdata",

pkg/gen/register.go

@@ -72,6 +72,7 @@ func RegisterService(s runtime.MCPServer, sd protoreflect.ServiceDescriptor, han
 		opts.NewMessage = DynamicNewMessage
 	}
 	schemaOpts := SchemaOptions{}
+	seenNames := map[string]bool{}
 
 	for i := 0; i < sd.Methods().Len(); i++ {
 		method := sd.Methods().Get(i)
@@ -86,11 +87,24 @@ func RegisterService(s runtime.MCPServer, sd protoreflect.ServiceDescriptor, han
 			comment = opts.CommentProvider(method)
 		}
 
-		// Generate tool schema
-		toolName := MangleHeadIfTooLong(
-			strings.ReplaceAll(string(method.FullName()), ".", "_"),
-			64,
-		)
+		// Resolve the tool name: the (mcp.v1.tool_name) option when set
+		// and valid, else the derived form. A configured name that
+		// collides with one already registered for this service falls
+		// back to the derived form, and if a configured name on an
+		// earlier method squatted on THIS method's derived name, a
+		// numeric suffix de-collides — AddTool is never called twice
+		// with the same name and nothing is silently dropped.
+		toolName := ToolNameForMethod(method)
+		if seenNames[toolName] {
+			toolName = MangleHeadIfTooLong(
+				strings.ReplaceAll(string(method.FullName()), ".", "_"),
+				64,
+			)
+			for base, i := toolName, 2; seenNames[toolName]; i++ {
+				toolName = MangleHeadIfTooLong(fmt.Sprintf("%s_%d", base, i), 64)
+			}
+		}
+		seenNames[toolName] = true
 
 		tool := runtime.Tool{
 			Name:            toolName,

pkg/gen/schema.go

@@ -530,6 +530,16 @@ func MangleHeadIfTooLong(name string, maxLen int) string {
 	if len(hashPrefix) > 10 {
 		hashPrefix = hashPrefix[:10]
 	}
+	// Providers disagree on the leading character of a tool name: Gemini
+	// requires a letter or underscore, while OpenAI and Anthropic also
+	// accept digits. A base-36 hash can start with a digit, and a mangled
+	// name leads with the hash -- Gemini then rejects the entire request
+	// with "Invalid function name". Map a leading digit onto 'g'..'p' so
+	// the name is valid on every provider; hashes that already start with
+	// a letter are unchanged, keeping existing tool names stable.
+	if c := hashPrefix[0]; c >= '0' && c <= '9' {
+		hashPrefix = string('g'+(c-'0')) + hashPrefix[1:]
+	}
 	if maxLen <= len(hashPrefix) {
 		return hashPrefix[:maxLen]
 	}
@@ -544,7 +554,7 @@ func MangleHeadIfTooLong(name string, maxLen int) string {
 // ToolForMethod generates the MCP tool definition for a given RPC method
 // descriptor (input and output JSON schemas plus name and description).
 func ToolForMethod(method protoreflect.MethodDescriptor, comment string) runtime.Tool {
-	toolName := MangleHeadIfTooLong(strings.ReplaceAll(string(method.FullName()), ".", "_"), 64)
+	toolName := ToolNameForMethod(method)
 	description := CleanComment(comment)
 
 	return runtime.Tool{

pkg/gen/schema_edge_cases_test.go

@@ -327,3 +327,57 @@ func TestMessageSchema_NoUnionKeywords(t *testing.T) {
 	// Regular non-oneof field is still in properties.
 	g.Expect(props).To(HaveKey("name"))
 }
+
+// Mangled names must be valid tool names on every provider. Gemini is
+// the strictest: the name must start with a letter or an underscore —
+// a base-36 hash prefix that starts with a digit broke Gemini-backed
+// agents outright (live failure: morningstar-securities
+// GetEquityResearchReport, 2026-06-10).
+func TestMangleHeadIfTooLong_GeminiSafeLeadingChar(t *testing.T) {
+	g := NewWithT(t)
+
+	// The exact name from the live failure: its hash starts with '5'.
+	const morningstar = "redpanda_mcps_morningstar_securities_v1_MorningstarSecuritiesService_GetEquityResearchReport"
+	got := MangleHeadIfTooLong(morningstar, 64)
+	g.Expect(got).To(HaveLen(64))
+	g.Expect(got).To(HaveSuffix("_MorningstarSecuritiesService_GetEquityResearchReport"))
+	first := got[0]
+	g.Expect(first >= 'a' && first <= 'z').To(BeTrue(),
+		"mangled name %q must start with a letter (Gemini requirement)", got)
+
+	// Deterministic across calls, and the exact expected rename:
+	// the old form was "5rl6rmshvl__..." — '5' maps to 'l'.
+	g.Expect(got).To(Equal("lrl6rmshvl__MorningstarSecuritiesService_GetEquityResearchReport"))
+
+	// The github_read hash also led with a digit ('6' -> 'm'), so its
+	// mangled name changes too — historically
+	// "64ghux5adn_github_read_v1_GitHubReadService_GetAuthenticatedUser".
+	const github = "redpanda_mcps_github_read_v1_GitHubReadService_GetAuthenticatedUser"
+	g.Expect(MangleHeadIfTooLong(github, 64)).To(Equal(
+		"m4ghux5adn_github_read_v1_GitHubReadService_GetAuthenticatedUser",
+	))
+}
+
+// Every mangled name, for any input, must satisfy the strictest
+// provider naming rule (Gemini): ^[a-zA-Z_][a-zA-Z0-9_.:-]*$.
+func TestMangleHeadIfTooLong_AlwaysProviderSafe(t *testing.T) {
+	g := NewWithT(t)
+	inputs := []string{
+		strings.Repeat("x", 100),
+		"0" + strings.Repeat("y", 100),
+		"redpanda_mcps_morningstar_securities_v1_MorningstarSecuritiesService_GetEquityResearchReport",
+		"redpanda_mcps_github_read_v1_GitHubReadService_GetAuthenticatedUser",
+		"a.b.c.d.e.f.g.h.i.j.k.l.m.n.o.p.q.r.s.t.u.v.w.x.y.z.a.b.c.d.e.f.g.h",
+	}
+	for _, in := range inputs {
+		for _, maxLen := range []int{1, 5, 10, 11, 20, 64} {
+			got := MangleHeadIfTooLong(in, maxLen)
+			if len(got) == 0 {
+				continue
+			}
+			first := got[0]
+			g.Expect((first >= 'a' && first <= 'z') || (first >= 'A' && first <= 'Z') || first == '_').To(BeTrue(),
+				"MangleHeadIfTooLong(%q, %d) = %q starts with %q", in, maxLen, got, string(first))
+		}
+	}
+}

pkg/gen/toolname.go

@@ -0,0 +1,64 @@
+package gen
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"google.golang.org/protobuf/proto"
+	"google.golang.org/protobuf/reflect/protoreflect"
+	"google.golang.org/protobuf/types/descriptorpb"
+
+	mcpv1 "github.com/redpanda-data/protoc-gen-go-mcp/pkg/mcpv1"
+)
+
+// validToolName is lowercase snake/kebab case within every LLM
+// provider's function-name rules (Gemini requires a leading letter or
+// underscore, OpenAI restricts the charset, 64 is the strictest length
+// limit). Lowercase is enforced deliberately: derived/mangled names
+// always contain an UpperCamel "<Service>Service_" segment, so a
+// lowercase-only configured name can never be mistaken for one by
+// downstream de-mangling heuristics (e.g. aigw's toolname.Short) —
+// configured names provably pass through them untouched.
+var validToolName = regexp.MustCompile(`^[a-z_][a-z0-9_-]{0,63}$`)
+
+// ValidateToolName reports whether a configured tool name is usable on
+// every LLM provider.
+func ValidateToolName(name string) error {
+	if !validToolName.MatchString(name) {
+		return fmt.Errorf("invalid tool name %q: must match %s (lowercase letter or underscore first; lowercase alphanumerics, underscores and dashes; max 64 chars)", name, validToolName)
+	}
+	return nil
+}
+
+// ConfiguredToolName returns the (mcp.v1.tool_name) option on the
+// method and whether it is set at all. Presence is reported separately
+// from the value so an explicitly authored empty string is
+// distinguishable from an absent option — the generator must reject
+// the former. The value is returned as authored; callers decide how to
+// handle an invalid one (the generator fails the build, the runtime
+// registration path falls back to the derived name).
+func ConfiguredToolName(method protoreflect.MethodDescriptor) (string, bool) {
+	opts, ok := method.Options().(*descriptorpb.MethodOptions)
+	if !ok || opts == nil {
+		return "", false
+	}
+	if !proto.HasExtension(opts, mcpv1.E_ToolName) {
+		return "", false
+	}
+	name, _ := proto.GetExtension(opts, mcpv1.E_ToolName).(string)
+	return name, true
+}
+
+// ToolNameForMethod resolves the MCP tool name for a method: the
+// (mcp.v1.tool_name) option when set and valid, otherwise the derived
+// full-name-based form, hash-truncated to 64 chars. Invalid configured
+// names fall back to the derived form here so dynamic registration
+// never publishes a provider-rejected name; the generator additionally
+// fails code generation on them so they are caught when authored.
+func ToolNameForMethod(method protoreflect.MethodDescriptor) string {
+	if name, ok := ConfiguredToolName(method); ok && ValidateToolName(name) == nil {
+		return name
+	}
+	return MangleHeadIfTooLong(strings.ReplaceAll(string(method.FullName()), ".", "_"), 64)
+}