Beacon MCP defines 3 tools with clear action verbs (find_, top_, agent_) and reasonable descriptions (100-180 chars). All tools have input schemas with type definitions and parameter descriptions. However, output schemas are not documented in the source code, parameter descriptions lack detail about constraints/formats, and error handling guidance is absent. No tool annotations (readOnlyHint) are visible. The server targets agent discovery, a read-only domain, but lacks the depth expected for production use (e.g., no pagination guidance, no error recovery hints).

• Document output schemas for all three tools. Specify fields returned (e.g., agent_id, name, stars, endpoints, tags, health_status) with types and descriptions.
• Enhance parameter descriptions with format constraints. E.g., 'query: Free-form capability search (e.g., "web scraping", "PDF extraction"). 1-200 characters.' and 'agent_id: GitHub slug format (owner/repo, e.g., "openai/gpt-4").'
• Add error recovery guidance. E.g., 'If no agents found, try broader keywords or check top_agents() for popular alternatives.'
• Add tool annotations: readOnlyHint=true for all three tools (they do not modify state). This signals to agents that retries are safe.
• Clarify pagination for find_agent. Document whether results are truncated, how to request next page, and recommend calling with limit=10-20 for best LLM reasoning.