Enhance MCP tool schemas and documentation for better LLM integration

[aperepel]

Summary

This PR significantly improves the MCP tool schemas and documentation to provide better guidance for LLM clients on how to structure tool calls properly.

Key Improvements

• Enhanced Pydantic Models: Added comprehensive Field() descriptions with examples, validation constraints, and clear usage guidance for all data models (Entity, Relation, ObservationAddition, ObservationDeletion)

• Detailed Tool Documentation: Improved all 9 MCP tools with:

  • Comprehensive docstrings explaining purpose and behavior
  • JSON examples showing exact expected input structure
  • Parameter descriptions with specific format requirements
  • Return value documentation
  • Warnings for destructive operations

• Fixed Type Annotations: Corrected return type annotations from incorrect specific types to ToolResult to match actual implementation

• Developer Documentation: Added CLAUDE.md with development commands, architecture overview, and testing guidance

Impact

These changes dramatically improve the developer experience by:

• Making tool schemas self-documenting with clear examples
• Providing LLM clients with precise guidance on expected data formats
• Reducing trial-and-error when constructing tool calls
• Adding proper validation and constraints

Example Before/After

Before:

entities: list[Entity] = Field(..., description="List of entities to create")

After:

entities: list[Entity] = Field(..., description="List of entities to create with name, type, and observations")
"""Create multiple new entities in the knowledge graph.

Example call:
{
    "entities": [
        {
            "name": "Alice Johnson",
            "type": "person",
            "observations": ["Software engineer", "Lives in Seattle", "Enjoys hiking"]
        }
    ]
}
"""

Test Plan

• Verified Pydantic models validate correctly with new Field constraints
• Confirmed all tools maintain backward compatibility
• Tested schema examples work as documented
• Validated type annotations with pyright

[aperepel]

Background. Previously, asking e.g. gpt-oss-120b to remember a fact caused failures, as it was missing lots of mandatory fields. This PR fixes those issues.

[a-s-g93]

thanks for your PR! Please see my notes. I think we can remove the Args: from docstrings since you added the Field objects to functions args.