SwarmKit exposes 8 tools across multiple example servers. Core authoring tools (validate_workspace, write_files, read_workspace) have reasonable descriptions (50-150 chars) and basic schemas with required fields. However, 5 of 8 tools lack parameter descriptions entirely (greet, search_docs, search_text, search_text_by_file, get_full_chunk), violating the critical rule that every parameter needs a description. Schemas are present but sparse, most parameters have only type and description, no constraints (enums, min/max, patterns). Output schemas are not documented. Error handling is absent from all tool descriptions. Tool naming is acceptable (verb_noun pattern) but composition is weak: search_docs and search_text are near-duplicates, and search_text_by_file adds a third variant without clear differentiation. No tool declares idempotency, permissions, or recovery guidance.

• Add descriptions to all parameters. For search_docs: 'n_results (1-20, default 5): number of semantic results to return' and 'source_filter (optional): restrict results to docs whose path contains this substring, e.g. "product-docs" or "api"'.
• Document output schemas for all tools. E.g., validate_workspace returns {status: 'valid'|'invalid', errors?: [{message, suggestion}]}; search_docs returns {results: [{source, content, score}], total_count}.
• Consolidate search tools: merge search_text and search_text_by_file into a single search_text tool with optional file_pattern parameter. Remove search_docs or clearly differentiate it (semantic vs keyword).
• Add error handling guidance to write_files: 'Returns success or error with details. If base_dir does not exist, create it. If files already exist, overwrite them. Validate YAML syntax before writing.'
• Add parameter constraints: search_docs.n_results as integer with minimum 1, maximum 20; search_text.limit as integer 1-100; source_filter as string pattern matching docs paths.