Skillmux defines 2 tools with clear, action-oriented names (resolve_skill, fetch_skill) and solid descriptions (145 - 180 chars, within baseline 194 avg). Both tools have complete input schemas with typed parameters and descriptions. However, output schemas are not documented in the visible code, LLMs cannot predict return structure. Parameter descriptions are adequate but lack format/constraint details (e.g., what constitutes a valid skill_id?). Error handling and recovery guidance are absent. No tool annotations (readOnlyHint, idempotentHint) despite both being read-only operations. Composition is sound: resolve_skill returns candidates; fetch_skill retrieves by ID, with optional request_id for audit correlation. Missing: output schema documentation, error classification, and tool annotations.

• Document output schemas for both tools. Specify: resolve_skill returns {candidates: [{skill_id, rank, score, ...}], total_count, ...}; fetch_skill returns {skill_id, content, sha256, supporting_files, ...}. Include field types and whether lists are paginated.
• Add readOnlyHint: true to both tool definitions in server.ts to signal to agents these are safe, non-destructive operations.
• Enhance parameter descriptions: skill_id → 'Unique skill identifier (alphanumeric, 1-255 chars)'; query → 'Natural-language task description (1-2000 chars, no special formatting required)'; top_k → 'Max candidates to return (1-100, default: 10, subject to server limit).'
• Add error handling section to tool descriptions: 'Returns error if skill_id not found, query is empty, or top_k exceeds server max. On error, try alternative skill_id or refine query.'
• Document default behavior for top_k in resolve_skill description and consider adding a max_top_k field to server capabilities so agents know the bound.