Spec-driven development plugin for OpenCode where specs become enforceable laws. Provides tool surface for change management, task workflows, testing, wisdom capture, and project orchestration.
This server has CRITICAL structural problems that prevent confident evaluation. While the codebase shows sophisticated architecture (role-based tool dispatch, Tier-4 MCP projection, tool-role-policy gates), the provided source code samples do NOT contain actual tool implementations, schemas, or parameter definitions. The 49 tools are NAMED and CATALOGUED but their input/output schemas, parameter descriptions, and error handling are NOT visible in the excerpts provided. Per the evaluation rule 'If you cannot see the actual tool definition in the source (only inferred): cap that tool's overall at 50', and since NONE of the actual tool schemas appear in the samples, I cannot verify the presence of JSON Schema definitions, parameter type annotations, or descriptions. The descriptions provided for each tool in the tool list (e.g., 'All status views...are agent-readable') are BRIEF (20-50 chars) and do not meet the 10-1024 character guideline for LLM-optimized descriptions. Most critically: the source excerpts show package.json fixtures, build scripts, and a partial import from tier4-tool-map.ts, but NO executable tool definitions. This forces scoring based on ABSENCE of verifiable evidence rather than PRESENCE of quality.
NO VISIBLE INPUT SCHEMAS for any of the 49 tools. The source code samples do not contain tool registration with JSON Schema definitions, parameter types, or parameter descriptions. Per evaluation rule: 'If a tool has NO input schema at all: its schema score MUST be 0.' This applies to ALL 49 tools, capping definition quality severely.
PROVIDE FULL TOOL IMPLEMENTATIONS: Submit source excerpts for all tool handler files (tools/*.ts) so JSON Schema definitions, parameter types, error handling, and output schemas can be verified. Currently, tools are only catalogued/named, not fully defined.
EXPAND TOOL DESCRIPTIONS to 50-200 characters following LLM-optimization guidelines. Example for adv_change_close: 'Close a change after approval gates are satisfied. Returns the closed change ID and final state. Call adv_gate_status first to check readiness.'
DOCUMENT ALL PARAMETERS with type, description, constraints, and examples. Example: 'change_id (string, required): The unique identifier of the change to close. Must be a valid UUID. Example: 550e8400-e29b-41d4-a716-446655440000'.
DOCUMENT OUTPUT SCHEMAS for every tool. Specify return type (object, array, string), field names, types, and descriptions. For list tools, include pagination: 'Returns object with fields: items (array of changes), total_count (number), next_cursor (string|null), has_more (boolean)'.
CONSOLIDATE TIER-4 DUPLICATES: Either remove the unprefixed variants (status, spec, etc.) from the public tool catalog and document them as internal-only mirrors, or unify to a single naming scheme. Reduce cognitive load on LLMs choosing between adv_status and status.
ADD PAGINATION to list tools (adv_change_list, adv_task_list, adv_spec, adv_tool_catalog, etc.). Accept limit (default 20, max 100) and offset/cursor parameters. Return total_count and next_cursor. Document result capping in descriptions.
Read-only single-tool schema and metadata projection; no handler invocation.
adv_tool_invokewritesource verified42/100
Strict in-process dispatcher through the canonical wrapped ToolDefinition.execute; preserves ToolContext, validation, authorization, approvals, recovery restrictions, and timeouts. Recursion exclusion (adv_tool_invoke, adv_tool_catalog, adv_tool_describe, execute) is enforced before any lookup or dispatch (addProviderToolSearch AC1-AC4).
adv_wip_stateread onlysource verified27/100
Cross-change work-in-progress aggregate read; no agent mutation surface — the worktree/session state it reports on is operator-owned.
TOOL DESCRIPTIONS ARE TOO BRIEF (most 8-25 characters). Examples: 'Approval-gated close' (21 chars), 'Change detail read' (18 chars), 'Tool-owned worktree creation' (28 chars). Current descriptions omit context about when to use each tool, dependencies, and return structure. All 49 tools score 0-25 on description because they lack LLM-optimizable depth.
TOOL IMPLEMENTATIONS NOT VISIBLE in source excerpts. The provided code shows only tier4-tool-map.ts (a Tier-4 projection factory) and package.json fixtures. The actual tool handler implementations in tools/*.ts are not included. Per evaluation rule 'If you cannot see the actual tool definition in the source (only inferred): cap that tool's overall at 50', the 49 tools are INFERRED from registry references and tier4-catalog listings, not directly visible. Cannot verify parameter validation, error handling, idempotency, or recovery guidance (patterns: recovery-guide, command-tool, error-classification).
DESTRUCTIVE AND IRREVERSIBLE TOOLS LACK VISIBLE ERROR HANDLING. Tools like adv_task_cancel (IRREVERSIBLE), adv_worktree_cleanup (DESTRUCTIVE), and adv_worktree_delete (DESTRUCTIVE) mention approval gates and dry-run mechanisms in their catalog descriptions, but the implementations are not visible. Cannot verify: (a) whether dry-run is mandatory before apply, (b) what error messages guide recovery, (c) whether the tool validates user intent, (d) rate limiting or safeguards.
TRANSPORT UNKNOWN. Per evaluation criteria: 'Unknown transport: HARD CAP 40/100.' The provided source does NOT indicate whether this is HTTP, SSE, STDIO, or WebSocket. The mcp-server directory exists (build:mcp-server script in package.json), but no transport configuration is visible. This prevents remote accessibility assessment and forces a protocol readiness cap.
DUPLICATE/NEAR-DUPLICATE TOOLS. Both adv_-prefixed (e.g. 'adv_status', 'adv_spec', 'adv_wisdom_list') and unprefixed Tier-4 variants (e.g. 'status', 'spec', 'wisdom_list') exist for the same operations. The 49-tool count includes both sets. Per pattern:tool, this violates single-responsibility and clarity, LLMs must reason about which variant to call, wasting context and increasing error likelihood. Either unify naming or clearly document the Tier-4 projection as read-only mirrors.
NO VISIBLE PARAMETER DOCUMENTATION. Cannot verify any tool's parameter descriptions, types, enums, defaults, or constraints from source. Cannot assess compliance with pattern:constrained-input, pattern:tool-description (params section), or rubric rules on field validation.
NO VISIBLE OUTPUT/RETURN SCHEMAS. Cannot verify: (a) what fields each tool returns, (b) whether responses include chaining IDs (e.g. if get_change returns change_id, do update_change and show_change accept that ID?), (c) pagination support (limit, offset, next_cursor, total_count), (d) whether results are capped at reasonable limits, (e) whether lists strip unnecessary metadata or return raw API responses.
ADD IDEMPOTENCY GUIDANCE: For write tools (adv_change_update, adv_task_checkpoint, etc.), document whether repeated calls with the same params produce the same result (idempotent) or compound effects. If idempotent, enable safe retries; if not, warn LLMs.
STRENGTHEN ERROR MESSAGES: For adv_task_cancel, adv_worktree_delete, adv_worktree_cleanup, ensure error responses guide recovery. Example: 'Cannot cancel task: task already completed. Call adv_task_list to find pending tasks.' Instead of generic 'Invalid state'.
EXPOSE DRY-RUN MECHANISMS explicitly. For destructive tools (adv_worktree_cleanup, adv_worktree_delete), mandate a 'dry_run' parameter (default true). Response must show what WOULD happen, with approval_token. Only apply (dry_run=false) when agent passes the token.
DOCUMENT TOOL PERMISSIONS AND ROLE GATES: The code references tool-role-policy.ts. Add to each tool's description which roles (operator, agent, etc.) can invoke it. Example for adv_ops_run_evidence_add: 'Ops-gated. Only callable by tools with ops_admin role. Requires approval_evidence.'
VALIDATE AND REJECT INVALID INPUTS with actionable errors. Example: if adv_change_create receives an invalid change_type, return: 'Invalid change_type: "feature". Must be one of: task, bugfix, hotfix, refactor. See adv_spec for allowed types.' Not a 400 with a stack trace.
ADD TOOL ANNOTATIONS (toolAnnotations feature): Mark tools as readOnlyHint (list/show/get tools), destructiveHint (delete/archive tools), idempotentHint (tools safe to retry). This helps MCP clients optimize behavior.
DOCUMENT CHAINING: For each write tool, list downstream tools that accept its output. Example for adv_change_create: 'Returns change_id. Pass to adv_change_update, adv_gate_status, adv_change_show.' Prevents discovery detours.
VERIFY TRANSPORT and make explicit: If HTTP, confirm it supports Streamable HTTP. If STDIO, add caveat that the server is not remotely accessible. Update README with transport details.
PROVIDE INTEGRATION EXAMPLE: Show how an agent would compose tools end-to-end. Example: 'Create change → check gate status → add evidence → complete gate → archive → reflect'. This clarifies tool ordering and reduces confusion.