agentmd provides 10 tools with explicit schemas and descriptions. Most tools have clear verb-noun naming (scan_agents, audit_agent, find_agent) and reasonable descriptions (avg ~150 chars). However, several critical gaps reduce quality: (1) Parameter descriptions are minimal or missing context (e.g., 'repo_path' lacks guidance on what happens if invalid); (2) Output schemas are not documented, tools return JSON but LLMs cannot predict field structure; (3) Error handling is generic (fail() wraps errors as text) with no recovery guidance; (4) Some parameters lack constraints (e.g., max_results, max_agents unbounded); (5) Tool descriptions omit prerequisites and side effects (e.g., find_agent with write=true modifies disk but this is buried in description). Naming is solid, but schema completeness and error guidance lag production standards.

• Document output schemas for all tools. Add a 'Returns' section to each tool description or create a separate schema map. Example: 'Returns: { agents: Agent[], count: number, repoPath: string }' so LLMs know what fields to expect.
• Add min/max constraints to numeric parameters. Change 'max_results: z.number().int().positive().optional()' to 'z.number().int().min(1).max(50).optional().describe("Max results to return (1-50, default: 3)")' to prevent absurd values.
• Enhance error messages with recovery guidance. Replace generic fail() with categorized errors: 'User not found. Try search_users() first.' or 'Invalid repo path. Ensure the directory exists and contains a .claude/agents folder.'
• Add dry-run or preview mode to all write operations. Modify find_agent, import_agent, fix_agent, and install_agent_pack to support a 'dry_run' parameter that shows what would be written without modifying disk.
• Clarify parameter dependencies in descriptions. Document that 'mode' in import_agent determines whether 'max_agents' is respected, and that 'write' in find_agent requires write permissions to .claude/agents.