README: annotate each tool with field origin (extraction / LLM / metadata)

Author: vicentebolea

README.md

@@ -54,28 +54,34 @@ Key environment variables:
 
 Data comes from the vtk-knowledge artifact; the query helpers are implemented in vtk-validate's tool layer.
 
-| Tool | Description |
-|---|---|
-| `vtk_get_class_info(class_name)` | Full class record (all fields below as one call) |
-| `vtk_search_classes(query, limit)` | Search classes by name or keyword |
-| `vtk_get_class_doc(class_name)` | Docstring for a class |
-| `vtk_get_class_synopsis(class_name)` | One-sentence synopsis |
-| `vtk_get_class_role(class_name)` | Pipeline role (`source` / `filter` / `mapper` / …) |
-| `vtk_get_class_input_datatype(class_name)` | Expected input data type |
-| `vtk_get_class_output_datatype(class_name)` | Produced output data type |
-| `vtk_get_class_methods(class_name)` | All methods with signatures |
-| `vtk_get_class_semantic_methods(class_name)` | Non-boilerplate callable methods |
-| `vtk_get_method_info(class_name, method_name)` | Full method record |
-| `vtk_get_method_doc(class_name, method_name)` | Method docstring |
-| `vtk_get_method_signature(class_name, method_name)` | Canonical method signature |
-| `vtk_get_class_module(class_name)` | `vtkmodules.*` import path |
-| `vtk_get_module_classes(module)` | All classes in a module |
-| `vtk_is_a_class(class_name)` | Check if a name is a valid VTK class |
-| `vtk_get_class_action_phrase(class_name)` | Action phrase (e.g. "mesh smoothing") |
-| `vtk_get_class_visibility(class_name)` | Visibility score 0.0–1.0 |
-| `vtk_get_class_inheritance(class_name)` | Full MRO chain |
-| `vtk_get_class_record_metadata(class_name)` | `{vtk_version, schema_version, content_hash}` |
-| `vtk_version_info()` | VTK version and enabled features for the loaded index |
+Each field in `VTKDocRecord` has one of three origins:
+
+- **extraction** — parsed directly from the VTK Python runtime (`help()`, introspection, MRO)
+- **LLM** — generated by an LLM enrichment pass during artifact build
+- **metadata** — versioning and integrity fields added at build time
+
+| Tool | Field(s) | Origin |
+|---|---|---|
+| `vtk_get_class_info(class_name)` | all fields | — (convenience: full record) |
+| `vtk_search_classes(query, limit)` | `class_name`, `module_name`, `synopsis` | — |
+| `vtk_get_class_doc(class_name)` | `class_doc` | extraction |
+| `vtk_get_class_methods(class_name)` | `methods` (name, signatures, doc) | extraction |
+| `vtk_get_method_info(class_name, method_name)` | single `VTKMethod` | extraction |
+| `vtk_get_method_doc(class_name, method_name)` | `method.doc` | extraction |
+| `vtk_get_method_signature(class_name, method_name)` | `method.signatures[0]` | extraction |
+| `vtk_get_class_inheritance(class_name)` | `inheritance` (full MRO chain) | extraction |
+| `vtk_get_class_role(class_name)` | `role` (`source`, `filter`, `mapper`, `renderer`, `scene`, …) | extraction |
+| `vtk_get_class_input_datatype(class_name)` | `input_datatype` | extraction |
+| `vtk_get_class_output_datatype(class_name)` | `output_datatype` | extraction |
+| `vtk_get_class_module(class_name)` | `module_name` (`vtkmodules.*` path) | extraction |
+| `vtk_get_module_classes(module)` | all `class_name`s in a module | extraction |
+| `vtk_get_class_semantic_methods(class_name)` | `semantic_methods` (non-inherited) | extraction |
+| `vtk_is_a_class(class_name)` | membership check | — |
+| `vtk_get_class_synopsis(class_name)` | `synopsis` (one sentence, ≤20 words) | LLM |
+| `vtk_get_class_action_phrase(class_name)` | `action_phrase` (noun phrase, ≤5 words) | LLM |
+| `vtk_get_class_visibility(class_name)` | `visibility_score` (0.0–1.0) | LLM |
+| `vtk_get_class_record_metadata(class_name)` | `vtk_version`, `schema_version`, `content_hash` | metadata |
+| `vtk_version_info()` | index-level `vtk_version`, class count, feature flags | metadata |
 
 ### Semantic search — via [vtk-index](https://github.com/vicentebolea/vtk-index)