AI Agent Governance Framework — Enforcement interface for SKILLs. Exposes resources (skill definitions, checklists, templates) and tools (submit_review, execute_tool) for Agent constraint enforcement via MCP.
P8 MCP Server has critical definitional gaps. Both tools are visible and registered in src/p8/enforcement/mcp_server.py with names, descriptions, and input schemas. However, descriptions lack LLM-optimization detail, schemas are incomplete, parameters have minimal guidance, output schemas are undocumented, and error handling does not provide actionable recovery paths. The server conflates two distinct responsibilities (audit review + OS execution) into a single tool interface without clear separation. Tool descriptions are narrative rather than constraint-driven.
Request OS action execution. Internally checked by SecurityGuard. Checks command safety and path restrictions against security.yaml rules.
Submit content for review. Internal check chain (invisible to Agent): Load guidelines.yaml, Load template.yaml, Reviewer.audit(content) — 5 static checks, All pass → APPROVED / Violations → P8AuditError
submit_review description is narrative (134 chars) but lacks actionable constraints. Does not state: what constitutes 'content', what format is expected, what violations trigger rejection, or when to retry.
execute_tool description (146 chars) is opaque. Does not specify which commands are blocked, what path restrictions apply, which operations (read/write/delete/create) are allowed for the skill, or what SecurityGuard violations look like.
'content' parameter in submit_review has no format guidance (plain text? markdown? structured JSON?). 'skill' defaults to 'prd' but no enum of valid skills is declared.
'command' and 'path' parameters in execute_tool are optional but neither schema nor description clarifies: can both be omitted? Are they mutually exclusive? What happens if both are provided?
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 43 | <=2025-11-25 | v2 |
'operation' parameter accepts 'read|write|delete|create' (inferred from description) but no enum constraint is present in schema. LLM may hallucinate invalid operations like 'append' or 'modify'.
Output schemas are undocumented. submit_review returns {error, passed, score, violations, action} but the structure of 'violations' array is not specified. execute_tool returns {command_check, path_check, allowed, action} but structure of checks is opaque.
Error handling provides limited guidance. P8AuditError returns {error, passed, score, violations, action} with action='REJECTED, Audit failed. Fix the issues in violations and resubmit.' but does NOT tell the LLM what the specific violations are or how to fix them structurally.
execute_tool returns {allowed: false, action: 'BLOCKED, You MUST abort this operation'} on security violations, but does NOT explain WHICH rule was violated, what the command/path matched, or what alternatives are safe.
Tool naming: 'execute_tool' is a generic verb-noun pattern that does not clarify the specific action. Does it execute shell commands? Filesystem operations? Both? More specific names like 'execute_command' + 'access_file' would disambiguate.
Descriptions reference internal implementation details ('Load guidelines.yaml', 'Reviewer.audit()', 'SecurityGuard') that agents should not know. Descriptions should focus on the LLM's perspective (what input to provide, what to expect), not on internal architecture.
No documentation of parameter relationships. For submit_review: does 'skill' determine which guidelines.yaml is loaded? For execute_tool: does 'skill' determine which security.yaml applies? These dependencies are invisible to the LLM.