diff --git a/kagenti-operator/api/v1alpha1/agentcard_types.go b/kagenti-operator/api/v1alpha1/agentcard_types.go
index a7306ea1..13020e4e 100644
--- a/kagenti-operator/api/v1alpha1/agentcard_types.go
+++ b/kagenti-operator/api/v1alpha1/agentcard_types.go
@@ -345,7 +345,9 @@ type SkillParameter struct {
 // +kubebuilder:printcolumn:name="LastSync",type="date",JSONPath=".status.lastSyncTime",description="Last Sync Time"
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 
-// AgentCard is the Schema for the agentcards API.
+// AgentCard binds an A2A agent card to a backing workload. The controller periodically
+// fetches the card from the referenced workload, verifies its JWS signature and SPIFFE
+// identity against the configured trust domain, and caches the result in status.
 type AgentCard struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
diff --git a/kagenti-operator/api/v1alpha1/agentruntime_types.go b/kagenti-operator/api/v1alpha1/agentruntime_types.go
index e5b8c722..69bc1a9d 100644
--- a/kagenti-operator/api/v1alpha1/agentruntime_types.go
+++ b/kagenti-operator/api/v1alpha1/agentruntime_types.go
@@ -124,7 +124,9 @@ type AgentRuntimeStatus struct {
 // +kubebuilder:printcolumn:name="Phase",type="string",JSONPath=".status.phase",description="Runtime Phase"
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 
-// AgentRuntime is the Schema for the agentruntimes API.
+// AgentRuntime attaches runtime configuration to a backing workload classified as an
+// agent or tool, providing per-workload overrides for SPIFFE identity and OpenTelemetry
+// tracing. The controller reports pod configuration coverage and phase in status.
 type AgentRuntime struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
diff --git a/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentcards.yaml b/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentcards.yaml
index 11f366d7..ae9c9ff9 100644
--- a/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentcards.yaml
+++ b/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentcards.yaml
@@ -56,7 +56,10 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: AgentCard is the Schema for the agentcards API.
+        description: |-
+          AgentCard binds an A2A agent card to a backing workload. The controller periodically
+          fetches the card from the referenced workload, verifies its JWS signature and SPIFFE
+          identity against the configured trust domain, and caches the result in status.
         properties:
           apiVersion:
             description: |-
diff --git a/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentruntimes.yaml b/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentruntimes.yaml
index 77e63922..97f3b0f1 100644
--- a/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentruntimes.yaml
+++ b/kagenti-operator/config/crd/bases/agent.kagenti.dev_agentruntimes.yaml
@@ -36,7 +36,10 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: AgentRuntime is the Schema for the agentruntimes API.
+        description: |-
+          AgentRuntime attaches runtime configuration to a backing workload classified as an
+          agent or tool, providing per-workload overrides for SPIFFE identity and OpenTelemetry
+          tracing. The controller reports pod configuration coverage and phase in status.
         properties:
           apiVersion:
             description: |-