A2ASearch MCP Server provides three well-named, focused tools with clear purposes. Tool names (search_agents, get_agent, list_agents) follow verb_noun conventions and are unambiguous. Descriptions are present and substantive (90-200 chars per tool). Input schemas are properly defined with JSON Schema types, enums where appropriate, and reasonable defaults. However, there are notable gaps: (1) Parameter descriptions lack detail about constraints and expected formats, e.g., 'limit' has no min/max bounds stated in the description, only in code logic; (2) Output schemas are undocumented, callers cannot predict what fields are returned or their types; (3) Error handling is minimal, API errors throw generic exceptions rather than guiding recovery; (4) No tool annotations (readOnlyHint, etc.) despite these being safe, read-only operations. The server is functionally sound but lacks the signal density and error resilience expected of production tools.

• Document the output schema for each tool. Define the response structure in the tool definition (e.g., search_agents returns an array of objects with fields: name (string), type (string), description (string), url (string), stars (number), capabilities (array of strings), languages (array of strings), health_score (number)). Include this in the tool metadata or as a comment in the code for clarity.
• Expand parameter descriptions with explicit constraints. For 'limit' across all tools, state: 'Number of results to return (minimum 1, maximum 20, default 10). Requests exceeding 20 are capped at 20.' For 'query', add: 'Free-text search string. Minimum 1 character. Supports partial matches. Case-insensitive.' For 'slug', add: 'Agent identifier in kebab-case (lowercase letters and hyphens only). Case-sensitive.'
• Add readOnlyHint annotations to all three tools. This signals to MCP clients that the tools are safe to call multiple times without side effects, enabling parallelization and caching. Example: 'readOnlyHint': true in the tool definition.
• Implement structured error recovery. Replace generic 'API error: {status}' with specific messages: 'A2ASearch API temporarily unavailable (HTTP {status}). Retry in a few seconds.' For search failures, suggest: 'No agents found matching "{query}". Try a broader search term or browse via list_agents().' For 404 on get_agent, suggest: 'Agent "{slug}" not found. Call list_agents() or search_agents() to discover available agents.'
• Validate slug format before calling the API. Reject slugs with uppercase letters, spaces, or special characters with a clear message: 'Invalid slug format. Use lowercase letters and hyphens only (e.g., my-agent-tool).'