AWOS Recruitment exposes a single tool 'search_capabilities' with a well-formed schema and reasonable description. The tool name is action-oriented (search_*) and the parameter types are properly defined. However, the description is minimal (95 chars), lacks critical context about when to use the tool vs alternatives, and does not explain the similarity scoring mechanism or result structure. The schema includes appropriate constraints (n_results default 10, threshold 0-100 range), but the response schema is not documented in the tool definition, LLMs cannot predict what fields to expect in results. No error handling guidance is provided. The server is single-purpose and simple, but lacks depth in documentation and composition context.

• Expand search_capabilities description to 150-250 chars. Include: WHAT (semantic similarity search over capability index), WHEN (discovering skills/tools/agents matching a natural language intent), expected result count, and how to interpret similarity scores. Example: 'Semantically search the capability registry for skills, tools, agents, or hooks matching a natural language query. Returns ranked results by similarity score (0-100). Use this to discover available capabilities before invoking them by name. Set threshold to filter low-confidence results.'
• Document output schema in tool description or as a structured return type hint. Example: 'Returns a list of {name, type, description, similarity_score} objects, sorted by score descending. similarity_score ranges from 0 (no match) to 100 (perfect match).'
• Clarify type_filter behavior: 'Optional filter to restrict results to a single type. Valid values: skill, tool, agent, hook. Case-sensitive. Omit to search all types.'
• Add error handling guidance: 'Returns an empty list if no results exceed the threshold. If the capability registry is not found, returns an error with path details, ensure AWOS_REGISTRY_PATH environment variable is set correctly. If query is empty, returns an error, provide at least one search term.'
• Consider adding a 'max_results' parameter (or rename n_results to max_results for clarity) with a hard cap documented in the description: 'Maximum number of results to return. LLMs: default 10 is recommended for context budgets; values above 50 may waste tokens on verbose results.'