Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This is a protoc-gen-mcp plugin that generates MCP tool definitions from Protocol Buffer service definitions. The server exposes 7 tools, all derived from example .proto files. While parameter schemas are well-defined with regex patterns and types, tool descriptions are minimal and several critical gaps exist: (1) No output schema documentation for any tool, LLMs cannot predict what fields will be returned, blocking downstream tool chaining. (2) Tool descriptions are generic one-liners that do not explain WHEN to use each tool vs similar ones (e.g., SayHello vs SayHelloWithQuery). (3) Composition issues: SayHello and SayHelloWithQuery are nearly identical, creating ambiguity. (4) UploadResource has NO input schema visible in the source, a hard failure. (5) No error handling guidance in any description. (6) No documentation of how pagination works (SearchResources accepts Page/PageSize but description doesn't explain semantics). Average tool score: 51. This reflects good schema coverage but poor descriptions and missing output documentation.
Tools (7)
GetNestedResourceread onlysource verified57/100
Retrieves nested resources from the system
GetUserProfileread onlysource verified62/100
Retrieves a user's profile information
SayHelloread onlysource verified58/100
Sends a simple greeting to the user
SayHelloWithQueryread onlysource verified52/100
Sends a greeting with additional query parameters
SearchResourcesread onlysource verified58/100
Searches for resources with advanced filtering and pagination
No tool returns output schema documentation. LLMs cannot predict response structure, breaking tool chaining and forcing guessing on field availability.
Descriptions are under 50 characters and provide no differentiation. 'Sends a simple greeting to the user' does not explain when to use SayHello vs SayHelloWithQuery. Generic descriptions fail to guide tool selection.
Document output schemas for all 7 tools in a structured format (JSON Schema or prose). For example, SayHello should document: {message: string, language: string, repeat_count: number}. This unblocks tool chaining and LLM reasoning.
Expand tool descriptions to 80-200 characters (baseline: 194 chars average for A+ tools). Include WHEN to use the tool vs similar ones. Example: 'Sends a greeting in the user-specified language. Use this for single-message greetings; call StreamGreetings to emit multiple greetings in sequence.'
Merge SayHello and SayHelloWithQuery into a single tool with a clear name (e.g., 'SendGreeting'). Document that this tool supports language and formality options in a single call.
Add explicit pagination semantics to SearchResources description: 'Returns page results (1-indexed). Request page 1 with page_size=20 to get the first 20 results. Response includes total_count for determining available pages.'
Add error handling guidance to each tool. Example for SearchResources: 'Returns empty results if no matches found. Returns error if page number exceeds available pages, agents should reduce page or decrease page_size.'
Clarify StreamGreetings output format in description. State whether output is line-delimited JSON, SSE chunks, or array. Include example: 'Returns chunked JSON objects, one per line, each with {message: string, sequence_number: int}'.
For complex response types (GetUserProfile, GetNestedResource), document key fields in descriptions. Example: 'Returns user profile with fields: user_id, profile_id, name, email, metadata (map). Use returned user_id for downstream calls to get_user_details.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↓ 3 points across a rubric change (v1 → v2)
47/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
F
47
<=2025-11-25
v2
2026-03-09
D
50
-
v1
SayHello and SayHelloWithQuery are semantically identical (same input schema, nearly identical descriptions). This violates composition principle: avoid multiple tools doing the same thing. LLMs will be confused about which to invoke.
SearchResources accepts Page and PageSize parameters but description does not explain pagination semantics (1-indexed vs 0-indexed, total count handling, next cursor).
No error handling guidance in any tool description. Error responses must tell LLMs what to do next (retry, ask user, abort). Current descriptions are silent on failure modes.
StreamGreetings description says 'Streams' but does not clarify output format (chunked text, JSON array, Server-Sent Events structure). Streaming semantics are undefined.
GetUserProfile and GetNestedResource return complex nested objects (Metadata maps, arrays of Permissions) but descriptions do not document structure. Agents cannot predict field availability.
UploadResource description is generic ('Uploads a resource with binary data support') but provides zero detail on input format, file size limits, supported MIME types, or response structure.
UploadResource
For UploadResource, add required input documentation: specify whether input is a file parameter, base64-encoded data, or multipart form. Document file size limits (e.g. 'max 100 MB'), supported MIME types, and response structure (file_id, url, etag).
Add parameter descriptions with examples and constraints to all tools. Current example: 'Name' has pattern ^[a-zA-Z0-9_]{3,50}$ but description just says 'The name of the person to greet'. Expand: 'The person's name (3-50 alphanumeric or underscore characters, e.g. alice_42).'
Document whether Repeat parameter in greeting tools is idempotent (calling with repeat=5 multiple times yields 5 greetings, not 25). State: 'This parameter controls output repetition. Calling with repeat=3 multiple times returns 3 greetings each call (idempotent).'
Add per-tool risk classifications. Mark SayHello as READ_ONLY (correct). Verify SearchResources is READ_ONLY and UploadResource is WRITE. Document security implications: 'UploadResource is a write operation. Verify caller has write:upload permission.'