Org-roam-claude has well-structured tool definitions with consistent naming (verb_noun pattern) and complete input schemas. All 10 tools have descriptions and typed parameters. However, descriptions are generic and lack LLM-optimization guidance (e.g., 'when to use this vs similar tools'). Parameter descriptions are minimal (1-2 sentences). Output schemas are not documented, LLMs cannot predict response structure. Error handling is absent; no recovery guidance. Write operations (create_note, update_note, add_link) lack confirmation/dry-run patterns. No tool annotations (readOnlyHint/destructiveHint). Composition is sound: tools chain well (search → get_note → explore_neighborhood), but some tools overlap (search_notes + find_by_tag both filter by tag).

• Document output schemas for all tools. Example: 'search_notes returns {results: [{id, title, tags, created}], total_count, has_more}'. LLMs need to know what fields to extract.
• Add tool annotations: mark read-only tools with readOnlyHint=true; mark create_note, update_note, add_link with destructiveHint=true. This enables LLMs to reason about side effects.
• Enhance descriptions with LLM-optimization guidance. E.g., 'search_notes: Use for title/content search. Use find_by_tag if you only have a tag. Returns up to 20 results; use limit to adjust.'
• Add confirmation/dry-run pattern to write operations. E.g., create_note could accept a 'dry_run' parameter that returns the generated note content without writing to disk.
• Implement error handling with recovery hints. E.g., 'Note not found: "xyz". Try search_notes(query="xyz") to find similar notes.' This guides agents to self-correct.