Educational repository containing multiple MCP server implementations demonstrating fundamental primitives, capabilities, transport mechanisms, and OpenAI Agents SDK integration
This is a multi-server educational repository with 5 tools across different modules. Tool definitions are present but severely underdeveloped. Naming is acceptable (verb-noun pattern: greet, read_doc_contents, edit_document, get_forecast, server_status), but descriptions are minimal (10-50 chars, well below the 194-char baseline). Input schemas are visible and typed, but parameter descriptions are sparse or missing. No output schemas documented. Error handling is absent. The codebase shows educational intent but lacks production-grade rigor. Most tools would score 30-45 individually.
Edit a document by replacing a string in the documents content with a new string.
Get weather forecast for a city.
Greet a person by name
Read the contents of a document and return it as a string.
Get server status and 2025-06-18 compliance info.
Descriptions are critically short (10-50 chars vs. 194-char baseline). 'Get weather forecast for a city' and 'Get server status and 2025-06-18 compliance info' lack context for LLM tool selection. No guidance on when to use each tool or what it returns.
Output schemas are not documented. LLMs cannot infer what fields greet(), read_doc_contents(), or get_forecast() return. This blocks downstream tool chaining and forces agents to guess at response structure.
Parameter descriptions are missing or trivial. 'doc_id' has description 'Id of the document to read' but no guidance on format (UUID? integer? string pattern?). 'city' in get_forecast has no constraints or examples.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 46 | 2026-07-28+ | v2 |
No error handling or recovery guidance. If edit_document fails (doc not found, old_str mismatch), there is no actionable error message. Agents cannot self-correct.
edit_document combines two concerns: finding the old string and replacing it. If the old_str appears multiple times, behavior is ambiguous. Consider splitting into separate tools or adding a 'position' or 'occurrence' parameter with clear documentation.