Random Tables MCP Server demonstrates solid tool definition quality with consistent schema coverage and reasonable descriptions. All 11 tools have explicit input/output schemas defined via Zod, which is well above baseline. Tool naming follows clear verb_noun patterns (create_table, roll_on_table, list_templates, etc.). Descriptions are present for all tools and most parameters, though some are repetitive template references and could be more action-focused. Output schemas are documented. Key weaknesses: (1) Several parameter descriptions are duplicated across tools without clarifying when to use one vs another (e.g., create_table vs update_table both describe the same template reference format); (2) Error handling is not visible in the sample code, no error classification, recovery guidance, or actionable error messages shown; (3) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications (create_table=WRITE, delete_template=DESTRUCTIVE); (4) Descriptions lack context about when to use each tool, e.g., when should an agent call roll_on_table vs evaluate_template?; (5) Parameter descriptions for optional fields don't state consequences of omission. Average tool description length ~120 chars (below the 194 baseline), which limits contextual guidance for LLM selection.

• Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to every tool. Map these from the existing Risk classifications: WRITE → destructiveHint=true, READ_ONLY → readOnlyHint=true, DESTRUCTIVE → destructiveHint=true. This helps agents understand which tools can be safely retried and which modify state.
• Expand list_tables and list_templates descriptions to 150+ chars explaining: (1) What structure is returned (summary of each table/template); (2) Whether pagination is supported; (3) When to use list vs get (e.g., 'Call this first to discover available tables before rolling on a specific one').
• Clarify the template reference format in a single shared location (e.g., in documentation or a README), and replace repetitive descriptions in create_table, update_table, create_template with: 'Entries/template can include nested table references. See documentation for format details.' This saves tokens and forces LLMs to consult the docs for the actual spec.
• Add explicit error handling to all tool implementations visible in code. Return typed error objects with category (retryable|user_fixable|fatal), invalid_value (if applicable), constraint, and suggested_action. Example: { error: 'table_not_found', table_id: 'invalid-id', suggestion: 'Call list_tables() to see available tables' }.
• Populate the 'filter' schema in list_tables with supported filter fields (e.g., name_contains, created_after, tags). If filtering is not yet implemented, remove the parameter and document how to discover tables (list all first, or use table_id if known).