The SpiceDB MCP server defines 6 tools with explicit schemas and descriptions in src/index.ts. However, critical issues limit overall quality: (1) Tool names lack action verbs, 'read-schema', 'read-relationships', 'check-permission' are acceptable, but 'write-relationship' bundles three operations (create/update/delete) into one tool, violating single-responsibility principle. (2) Output schemas are completely undocumented, no response field definitions, types, or example structures are visible in the code. (3) Parameter descriptions are minimal (5-15 chars on average) and lack actionable guidance on formats, ranges, or constraints. (4) No error handling guidance is present, tools do not document what happens on failure, recovery steps, or how LLMs should react. (5) The write-relationship tool accepts an 'operation' enum but does not describe the differences in return values or side effects between create/update/delete. (6) No idempotency guarantees or confirmation patterns for destructive operations. These gaps place the server solidly in the C-D range despite correct schema structure.
Output schemas completely undocumented. No visible response field types, structures, or examples for any tool. LLMs cannot predict what data is returned, forcing them to guess field names for downstream tool chaining.
write-relationship tool bundles three distinct operations (create, update, delete) into one tool with a string enum parameter. Violates single-responsibility principle. Should be split into create-relationship, update-relationship, delete-relationship so the LLM understands destructiveness and idempotency semantics per operation.
Parameter descriptions are extremely brief (5-15 characters) and lack actionable constraints. Example: 'Filter by resource object type (optional)' tells LLM nothing about format (e.g. is it 'Document' or 'document'? are underscores allowed?).
read-relationships
Recommendations
Document output schemas for all 6 tools. For each, list response fields with types and descriptions. Example for check-permission: '{allowed: boolean, trace?: object, reasoning?: string}'. Use structured JSON Schema format visible to code and LLM.
Split write-relationship into three tools: create-relationship (with idempotent key), update-relationship, delete-relationship. Mark delete as destructive in tool annotations (destructiveHint: true). This lets LLM understand semantics and ask for confirmation on delete.
Expand all parameter descriptions to 50-100 chars with format/constraint details. Example: 'resourceType (string, 1-64 lowercase alphanumerics + underscore, required): SpiceDB object type defining the resource, e.g. "document", "user_group". Call read-schema first to discover valid types.'
Add error handling guidance to each tool description or in a dedicated error response object. Document common failure modes: SpiceDB unreachable, invalid resourceType, permission denied, malformed relationship tuple. For each, provide a next-step hint for the LLM.
Add limit and offset parameters to read-relationships, lookup-resources, lookup-subjects. Cap default limit to 50 items max. Document that results are truncated and provide a total count. Example: 'lookup-resources(permission: "view", subjectType: "user", limit: 20, offset: 0) -> {resources: [...], total: 1247, limit: 20, offset: 0, hasMore: true}'.
For read-schema, either paginate the schema (split into sections) or compress output. If schema is large, return a summary with 'Call read-schema(format: "full") to retrieve complete schema' guidance.
No error handling guidance. Tools do not document what happens on invalid input, permission denial, SpiceDB connection failure, or malformed relationships. 'Invalid resourceType: must match /^[a-z_]+$/. Try read-schema to see valid types.'
No pagination or result limits documented. read-schema could return megabytes of schema text; read-relationships and lookup-* tools could return thousands of records. No such parameters or guidance visible.
check-permission tool does not document output format. Is the response a boolean (true/false), or an object with {allowed: true, reason: '...', trace: ...}? LLM cannot chain this output into other tools without guessing.
Tool description lengths vary widely (22 - 46 chars). Example: 'Check if a subject has a permission on a resource' (50 chars) does not explain when to use this vs lookup-resources, what trace information is returned, or how permission inheritance works.
Add a dry_run parameter (boolean, default false) to write-relationship. When true, return what would happen without committing. This prevents accidental deletes and aligns with pattern:confirmation-request.
Clarify subjectRelation parameter across tools. Is it a relation name (e.g. 'member') or a full tuple string (e.g. 'user:alice#member')? Document the exact format and whether it's optional vs required in different contexts.
Add tool annotations (once supported in this MCP SDK version) to mark read-* tools as readOnlyHint: true and write-relationship delete operation as destructiveHint: true. This signals to LLM clients how to handle these operations.
Document tool composition and chaining. Example: 'To find all resources user:alice can view, call lookup-resources(permission: "view", subjectType: "user", subjectId: "alice"). Response includes resourceType and resourceId, which can be passed to read-relationships(resourceType, resourceId) for details.'