mcp-schema-enum-regression
Keep generated MCP schemas strict-client compatible by avoiding nullable enum signatures.
40
38%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.squad/skills/mcp-schema-enum-regression/SKILL.mdQuality
Discovery
40%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description targets a very narrow and specific technical concern (nullable enum signatures in MCP schemas), which gives it strong distinctiveness but limits its usefulness as a skill selector. It lacks a 'Use when...' clause, making it unclear when Claude should activate this skill, and the single action described doesn't convey the full scope of what the skill covers.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when generating or reviewing MCP tool definitions, JSON schemas for MCP servers, or when enum types appear in MCP schema outputs.'
Expand the 'what' to cover more concrete actions, e.g., 'Validates and corrects MCP tool schemas to ensure strict-client compatibility, removes nullable enum patterns, and enforces compliant type definitions.'
Include natural trigger terms users might use, such as 'MCP tool definition', 'JSON schema', 'MCP server', 'enum type', or 'schema validation error'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names a specific domain (MCP schemas) and a concrete action (avoiding nullable enum signatures), but it only describes one narrow action rather than listing multiple specific capabilities. | 2 / 3 |
Completeness | The description answers 'what' (keep MCP schemas strict-client compatible by avoiding nullable enum signatures) but has no explicit 'when' clause or trigger guidance, which per the rubric should cap completeness at 2, and the 'what' itself is narrow enough that this falls to 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant technical keywords like 'MCP schemas', 'nullable enum', and 'strict-client compatible', but these are fairly jargon-heavy. Users might say things like 'MCP tool definition', 'schema validation', or 'enum type error' which are not covered. | 2 / 3 |
Distinctiveness Conflict Risk | This is a very specific niche — MCP schema generation with nullable enum constraints — making it highly unlikely to conflict with other skills. | 3 / 3 |
Total | 8 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill identifies a real and specific problem (nullable enums in MCP schemas) and provides useful heuristics and anti-patterns. However, it falls short on actionability by lacking executable code examples and on workflow clarity by not defining a clear step-by-step process with validation checkpoints. The referenced example files are not available in the bundle, weakening progressive disclosure.
Suggestions
Add a concrete, executable code snippet showing how to recursively validate enum arrays in a schema (e.g., a C# method that calls ListToolsAsync() and checks each enum node).
Define a clear numbered workflow: 1) Run ListToolsAsync, 2) Validate all enum nodes, 3) Fix nullable enums by converting to optional strings, 4) Re-validate, 5) Confirm no sentinel values remain.
Include a before/after example of a problematic schema vs. a corrected schema to make the anti-patterns concrete.
Either include the referenced example files in the bundle or replace file path references with inline code excerpts showing the key patterns.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and avoids over-explaining basics, but some bullet points are somewhat abstract and could be tightened. Phrases like 'Treat nullable enum parameters in MCP tool signatures as the hazard point' are slightly verbose for what they convey. | 2 / 3 |
Actionability | Provides specific file path references and names concrete patterns (e.g., `ListToolsAsync()`, `[FromString]`), but lacks executable code snippets or copy-paste ready examples. The guidance is directional rather than fully concrete—no actual code showing how to recurse schema nodes or how to emit optional strings. | 2 / 3 |
Workflow Clarity | There is no clear sequenced workflow. The 'Patterns' section lists heuristics but doesn't define a step-by-step process with validation checkpoints. For a skill involving schema generation and validation (where invalid schemas break clients), the absence of an explicit test-fix-verify loop is a significant gap. | 1 / 3 |
Progressive Disclosure | The content is reasonably organized into Context, Patterns, Examples, and Anti-Patterns sections. However, the 'Examples' section only references file paths without any bundle files to back them up, and there are no links to deeper reference material. The structure is adequate but the references are unresolvable. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- sbroenne/mcp-server-excel
- Commit
e8764a6
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.