Canvas-mcp demonstrates solid tool design with clear naming conventions (verb_noun pattern), comprehensive parameter descriptions, and well-documented schemas. All 11 tools have descriptions and input schemas with type definitions. Strengths: safety guardrails (dry-run defaults on destructive ops), good parameter constraints (enums, ranges), and clear dependency hints ('Use canvas_list_courses first'). Weaknesses: output schemas are not formally documented in the source code (inferred from eval tests), some parameter descriptions could be more prescriptive about format/constraints, and error handling guidance is minimal. The eval suite demonstrates schema awareness but doesn't substitute for explicit output documentation in tool definitions.

• Add explicit output schemas to all tool definitions. Document return types as JSON Schema (e.g., 'Returns: { courses: [{ course_id: number, name: string, current_grade: string }], count: number }'). This enables LLMs to plan multi-step workflows without guessing.
• Enhance parameter descriptions with 'why' context. E.g., 'days (1-90): Canvas API limits planner lookups to 90 days; values >90 are clamped. Recommend 14-30 for typical use.' This helps LLMs understand constraints, not just obey them.
• Add error recovery hints to tool descriptions. E.g., 'If canvas_find_person returns no results, the person may not be enrolled in the course. Try canvas_list_courses to verify the course_id, or ask the user for the person's email.'
• Document the dry-run behavior explicitly. E.g., 'confirm=false (default): validates submission format and permissions, shows preview, does NOT submit. confirm=true: actually submits and returns confirmation. Dry-run is safe to call multiple times.'
• Add a 'Chaining' section to tool descriptions that reference downstream tools. E.g., canvas_list_courses → canvas_list_assignments → canvas_get_assignment → canvas_submit_assignment. This guides LLM planning and reduces discovery overhead.