Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server demonstrates solid schema structure and parameter validation patterns, with all 16 tools having explicit input schemas registered via src/infrastructure/mcp/ToolRegistry.ts and src/infrastructure/mcp/sddToolDefinitions.ts. However, parameter descriptions are inconsistently applied across tools, and tool descriptions themselves are brevity-focused but lack depth on WHEN to use the tool vs alternatives and any prerequisites. Many tools accept complex conditional schemas (allOf constraints) but lack clear guidance on how these conditions interact. The tool naming follows verb_noun convention well (sdd-init, sdd-requirements, sdd-design, sdd-approve, sdd-status), but several tools conflate multiple concerns (e.g., sdd-tasks both submits artifacts AND triggers review). Error handling is not evident in the schema definitions, no error classification or recovery guidance visible. Output schemas are not documented in the visible code.
Tool descriptions are uniformly sparse (20-45 characters). Examples: 'sdd-review-test-cases' = 'Record review for an exact tasks revision' (43 chars), 'sdd-steering' = 'Create or update project steering documents' (43 chars). These fall below the 50-200 char baseline for LLM-optimized descriptions and lack WHEN/WHY context, alternatives, or prerequisites.
Parameter descriptions are missing or minimal across most tools. For example, sdd-requirements has properties 'expectedRevision' and 'expectedArtifactSha256' with no visible descriptions in the schema; sdd-tasks has 'reviewTestCases' (boolean) with no explanation of what enabling it does. Per the rubric, every parameter must have a description so LLMs can infer parameter meaning.
Expand tool descriptions to 50-200 characters, following the pattern: 'What it does' (e.g., 'Registers a new SDD feature and its metadata') + 'When to use it' (e.g., 'Call this before sdd-requirements to establish governance') + 'What it returns' (e.g., 'Returns feature ID and initial artifact revision'). Example for sdd-init: 'Registers a new SDD feature under .spec/specs with governance rules. Call this first before submitting requirements. Returns feature ID, initial revision, and status. Requires featureName matching ^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$ and a 1-20000 char description.'
Add descriptions to every parameter in the JSON schemas. At minimum: featureName -> 'Feature identifier under .spec/specs, 1-80 alphanumeric/._- chars'; expectedRevision -> 'Expected artifact version number (0 = initial); used for optimistic concurrency control'; expectedArtifactSha256 -> 'SHA256 hash of the artifact content for validation; null = skip validation'; reviewTestCases -> 'If true, triggers automatic test case review workflow; if false, test review is manual'.
Split sdd-tasks into two tools: (1) sdd-submit-tasks -> accepts featureName, content, expectedRevision, expectedArtifactSha256, returns success/revision. (2) sdd-request-test-review -> accepts featureName, taskRevision, returns review status. This lets agents sequence them independently and compose them as needed per pattern:tool.
Simplify sdd-spec-impl by extracting conditional branches into separate tools: (1) sdd-start-task (action=start), (2) sdd-record-test-result (action=record-red|green with evidence), (3) sdd-complete-task (action=complete with affectedArtifacts), (4) sdd-block-task (action=block with blocker reason). Each tool has a single, clear purpose and required parameters are fixed (no conditionals).
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
sdd-tasks and sdd-spec-impl combine multiple concerns. sdd-tasks submits an artifact AND conditionally triggers test case review (reviewTestCases param). sdd-spec-impl records progress with 7 conditional branches (evidence required for red/green/complete, affectedArtifacts required for complete, blocker required for block). Per pattern:tool, each tool should do exactly one thing; complex conditional logic should be split into separate tools or wrapped in a stateful wizard.
No documented output schemas visible in the code. Tools like sdd-status, sdd-context-load, and sdd-quality-check have no visible return type documentation. Per the rubric, LLMs need to know what fields to expect so they can plan downstream calls. Without documented schemas, agents cannot compose tool chains reliably.
No error handling or recovery guidance visible in tool definitions. No examples of actionable error responses (e.g., 'Feature not found. Valid features: feature-1, feature-2'), error categorization (retryable vs fatal), or suggested next steps. Agents will receive errors with no context on how to proceed.
Conditional schema constraints (allOf) are used in sdd-context-load and sdd-spec-impl without explanation in descriptions. For example, sdd-context-load requires mode='full' when includeUnapproved=true, but this is only expressible in JSON Schema allOf, not documented in the description. LLMs cannot parse allOf constraints from descriptions alone.
sdd-quality-check accepts 'code' (required) and 'language' (optional, no enum defined). The description says 'Perform code quality analysis' without indicating which languages are supported or what happens if language is omitted. An agent cannot know if it should pass 'python', 'py', 'Python', or guess the language.
sdd-context-load has a complex mode/phase/maxEstimatedTokens interaction with no clear guidance. Should an agent call with mode='compact' first to estimate tokens, then retry with mode='full'? What happens if maxEstimatedTokens is exceeded? The tool description does not answer these questions.
sdd-context-load
Document output schemas for all tools. Example for sdd-status: 'Returns { featureName: string, currentPhase: "requirements"|"design"|"tasks"|"implementation", phases: { requirements: { revision: int, approved: bool, approvedAt: ISO8601 }, design: {...}, ... }, lastModified: ISO8601 }'.
Add error guidance to descriptions. Example for sdd-init: 'Error: Feature already exists -> Try sdd-status featureName to check status. Error: Invalid featureName -> Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$; try a 2-8 char alphanumeric name. Error: Description too long -> Reduce to <=20000 chars.'
For sdd-context-load, document the mode/phase/maxEstimatedTokens interaction in the description: 'Load context for a feature phase. mode: compact (summary only, ~500 tokens), standard (details, ~2000 tokens), full (all artifacts, ~5000+ tokens). phase: which SDD phase to load. maxEstimatedTokens: cap response size; if exceeded, mode is auto-downgraded. includeUnapproved=true requires mode=full.'
For sdd-quality-check, add an enum for language: ['javascript', 'typescript', 'python', 'java', 'go', 'rust', 'csharp', 'other']. Document in the description: 'Analyze code quality. language: detected language or one of the enum values; if omitted, attempt auto-detection. Returns issues array with severity (error|warning|info), line, message, suggestion.'
Add idempotency guidance: 'sdd-approve, sdd-review-test-cases, and sdd-spec-impl with action=complete are idempotent when called with the same expectedRevision and expectedArtifactSha256. Agents may safely retry without side effects.' This signals to LLMs which tools are safe to retry.
For write tools (sdd-init, sdd-requirements, sdd-design, sdd-tasks, sdd-approve, sdd-spec-impl, sdd-steering*), add a note in the description: 'This modifies server state. Confirm with the user before executing in critical contexts.' This mirrors pattern:confirmation-request.
Document featureName constraints consistently. Every tool that accepts featureName should have the same description: 'Feature name registered via sdd-init. Must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$. Examples: my-feature, Feature_1, feature.v2.'
Add chaining IDs to response schemas. If sdd-init returns a featureName, all downstream tools can reference it directly. If sdd-requirements returns an artifactSha256, downstream tools like sdd-approve can use it without a second lookup. Document in output schemas which IDs chain to which tools.