Cograph demonstrates solid tool design with consistent naming (verb_noun pattern), comprehensive parameter schemas with types and constraints, and clear descriptions. All 11 tools have descriptions (avg ~120 chars) and input schemas with typed parameters. However, output schemas are not documented in the source, parameter descriptions lack dependency hints and format guidance, and error handling patterns are absent. No tool annotations (readOnlyHint/destructiveHint) despite clear risk profiles. The write_page tool is a state-changing operation but lacks confirmation/dry-run pattern.

• Document output schemas for all tools. For search_code and search_docs, specify: returns array of {code_chunk/doc_chunk, file_path, line_range, relevance_score}. For list_children, specify: returns array of {name, type, signature, qualified_name}. This enables LLMs to chain tools and extract the right fields.
• Add tool annotations to the MCP tool registration: readOnlyHint=true for all read tools (read_node_by_qn, find_by_name, list_children, list_by_file, get_neighbors, search_code, search_docs, read_file, grep, list_files); destructiveHint=true for write_page. This is a current spec pattern (2026-07-28) that improves agent safety.
• Implement a confirm_before_execute pattern for write_page. Instead of shipping markdown immediately, return a preview with a confirmation step. E.g., return {preview: markdown, confirm_token: '...'} and require a separate confirm_write_page(confirm_token) call. This prevents accidental page overwrites.
• Enhance parameter descriptions with format and constraint guidance. E.g., grep: 'Regex pattern (PCRE syntax, max 1000 chars). Use (?i) for case-insensitive matching.' read_file: 'offset must be >= 1; limit capped at 400 lines to prevent context explosion.' list_files: 'glob pattern (e.g., **/*.go, pkg/auth/**); null defaults to **/* (all files).'
• Add error handling guidance to tool descriptions. E.g., search_code: 'Returns up to top_k results. If query is too broad, results may be truncated, refine the query or increase top_k. If no results found, try search_docs or grep with a simpler pattern.' write_page: 'If markdown is malformed, returns validation error with line number, fix and retry.'