TypeScript SDK for Gopher Orch - AI Agent orchestration framework with native performance and MCP server examples
This is a framework/SDK server (gopher-mcp-js) with 4 example tools. Tool definitions are present with explicit names, descriptions, and input schemas visible in the source. However, there are significant gaps: (1) all tools lack parameter descriptions despite having enum constraints; (2) no output schemas are documented anywhere; (3) error handling guidance is absent; (4) descriptions are minimal and don't explain WHEN to use each tool or what prerequisites exist; (5) no composition guidance for chaining tools. The 'health' tool has an empty input schema but a valid description. The 'get-user-data' and 'admin-action' tools have constrained parameters (enums) but those enums lack supporting descriptions. Security-critical tool 'admin-action' declares a WRITE risk but has no mention of scope enforcement or permission validation in its description. This is typical of early-stage example/demo code rather than production-grade tooling.
Perform administrative action (requires mcp:admin scope)
Get data for the authenticated user (requires authentication)
Check server health (no authentication required)
Get personalized profile information using authentication context
All 4 tools lack output schema documentation. LLMs cannot plan downstream tool chaining or extract fields without knowing what fields are returned. This violates the 'Document the output schema' critical check.
Parameter descriptions are completely absent. The 'action' enum in admin-action has values ['list-users', 'system-status', 'clear-cache'] but no explanation of what each does or what they return. The 'dataType' enum in get-user-data has values ['profile', 'preferences', 'activity'] but LLMs must infer the meaning. This violates 'Every parameter needs a description explaining what it controls.'
Tool descriptions are generic and lack WHEN/WHY context. 'Get personalized profile information' and 'Perform administrative action' do not explain when to call each tool, when one tool is preferred over another, or what the prerequisites are. This violates the rule 'Write descriptions as if prompt-engineering. State WHAT, WHEN, and prerequisites.'
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | <=2025-11-25 | v2 |
Security-critical tool 'admin-action' (marked WRITE risk) lacks error handling and recovery guidance. No mention of whether the operation is idempotent, reversible, or requires confirmation. Description does not state 'requires mcp:admin scope' formally or explain what happens if the user lacks permission. This violates the pattern 'Irreversible operations should support a dry-run or confirmation step.'
Tool naming mixes conventions: 'health', 'get-user-data', 'admin-action', 'user-profile' use hyphens instead of snake_case. Arcade pattern baseline strongly prefers snake_case (e.g. 'get_user_data'). Inconsistent naming makes it harder for LLMs to infer intent and compose tools.
No error handling or recovery guidance documented for any tool. If 'get-user-data' fails because the user is not found, what should the LLM do next? Should it retry, ask the user, or call search_users()? If 'admin-action' is denied due to insufficient permissions, what's the recovery path? This violates 'Error responses must tell the LLM what to do next.'
Authentication and scope enforcement are mentioned in descriptions but not formalized. 'get-user-data' says 'requires authentication' and 'admin-action' says 'requires mcp:admin scope', but there is no explicit scope or permission declaration visible in the tool schemas. This violates 'Each tool should declare what permissions it requires (e.g. read:email, write:calendar).'