skill-search is a semantic search server with 4 well-named tools that follow verb-first conventions. All tools have descriptions (10-200+ chars), which is strong. However, input schemas are partially visible but incomplete: only 2 of 4 tools show explicit parameter type definitions in the provided code sample. The reindex and health tools lack visible schema details. Descriptions are substantive and action-oriented, explaining WHAT and WHEN to use each tool. Error handling is mentioned (health detects drift, reindex fails loud) but recovery guidance in responses is not visible in the code. Naming is clear (search_skills, get_skill, reindex, health) and follows Arcade patterns. Parameter descriptions exist where visible (query, name, force), but the reindex description could clarify parameter constraints better. Output schemas are not documented in the provided code, descriptions mention what tools return (ranked skills, full SKILL.md, warnings) but formal schema documentation is missing. Overall, this is a solid B-/C+ server: good naming and description tone, but incomplete schema visibility and missing output documentation.

• Document the full output schema for each tool in the description or a separate schema field. Example for search_skills: 'Returns an array of objects, each with {name: string, description: string, score: number (0-1)}, sorted by relevance score descending.'
• Add TOP_K and pagination parameters to search_skills so the LLM can control result count. Example: 'search_skills(query: string, top_k: int = 6, skip: int = 0)'. Document: 'top_k must be 1 - 50 (default 6).'
• Formalize error responses. In reindex, if embedding fails, return: {success: false, error: 'Embedding service unavailable', category: 'retryable', recovery: 'Retry after 30 seconds or check SKILL_EMBED_BACKEND configuration.'}. In health, return warnings as a structured {warnings: [{message: string, severity: 'info'|'warning'|'error'}]}.
• For reindex, clarify the force parameter: 'boolean (default false). If false, only skills with changed content are re-embedded (hash-based incremental). If true, all skills are re-embedded from scratch.' Add example: '...force=true is useful after model upgrades.'
• Add dependency hints to tool descriptions. Example for get_skill: 'Prerequisites: the skill must exist on disk (see health() to diagnose if the index is stale). Typically called after search_skills() returns a skill name.'
• Document TOP_K limit as a tool constraint. Example: 'search_skills returns at most 6 results per query. Adjust via SKILL_TOP_K environment variable (server-side only).'
• Explicitly state which tools are read-only vs. write (Risk field is present but not reflected in descriptions). Example: search_skills, get_skill, health are read-only (safe to retry). reindex modifies the index (safe to retry, idempotent via content hash).

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry