Three tools with complete input schemas and basic descriptions, but significant gaps in parameter documentation and output schema clarity. All tools are READ_ONLY operations on a skills directory. Naming is clear (verb_noun pattern: skillsmith_lint, skillsmith_score, skillsmith_graph). Descriptions exist but are brief (50-80 chars) and lack actionable context for LLM selection. Parameter descriptions are minimal: 'path' is documented but 'format' enum lacks explanation of output differences. No documented output schemas, error handling guidance, or recovery paths. Tools appear well-implemented internally but lack the LLM-facing documentation needed for confident agent selection and chaining.
Build the skill dispatcher graph. Returns nodes and edges as JSON, or an HTML visualization.
Lint a skills directory. Returns issues with severity/code/scope.
Score each skill in a directory on a 100-point rubric. Returns per-skill scores and average.
Output schemas not documented. Tools return structured data (issues with severity/code/scope, per-skill scores, graph nodes/edges) but LLMs cannot plan downstream operations without knowing response field names and types.
Parameter 'format' enum lacks descriptions. LLMs cannot infer the semantic difference between 'text' and 'json' output or when to choose each. Description should explain: 'json returns structured data for programmatic processing; text returns human-readable terminal output.'
Tool descriptions are under 100 chars and lack context for LLM selection. 'Lint a skills directory' does not explain when to call this vs score or graph, what 'linting' means in this domain, or what issues it detects. Descriptions should be 50-200 chars with actionable context.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | 2026-07-28+ | v2 |
No error handling guidance. If a path is invalid, permissions denied, or no skills found, LLMs receive no recovery hints. Error responses should guide: 'Path not found. Verify the directory exists and contains skill files.'
No tool annotations. All three tools are read-only and idempotent, but lack readOnlyHint and idempotentHint annotations. This prevents LLMs from optimizing retry logic and caching strategies.