Merge pull request #566 from future-agi/fix/rewrite-tracing-annotation-spans

rewrite manual tracing adding annotation spans

Author: hadarishav

src/pages/docs/observe/features/manual-tracing/annotating-using-api.mdx

@@ -7,46 +7,26 @@ description: "Label spans with custom tags, human feedback, and notes using the
 Looking for the new unified Annotations system? Check out the [Annotations documentation](/docs/annotations) for annotation queues, managed workflows, and the Scores API.
 </Tip>
 
-## What it is
+## About
 
-**Annotations** let you label spans with additional information — custom tags, criteria, human feedback, or notes — directly on your trace data. You create annotation labels in the Future AGI UI and then add, update, and retrieve annotations programmatically using the `/tracer/bulk-annotation/` API endpoint.
+Traces show what happened but not whether the result was correct, helpful, or safe. Annotations close that gap by attaching labels, scores, notes, and human feedback directly to spans. The `/tracer/bulk-annotation/` API lets this be done programmatically, at scale, across hundreds of spans in a single request. Annotated spans can then be filtered by quality, exported as golden datasets, or used in RLHF workflows.
 
-## Use cases
+---
+
+## When to use
 
-- **Label your data** with custom tags and criteria for filtering and analysis.
-- **Add custom events** to your spans for richer trace context.
-- **Create a golden dataset** for AI training by annotating high-quality examples.
-- **Add human feedback** to spans for RLHF and evaluation workflows.
+- **Label data for filtering and analysis**: Tag spans with custom criteria so they can be searched and grouped in the dashboard.
+- **Build golden datasets**: Annotate high-quality examples for AI training and fine-tuning.
+- **Add human feedback**: Attach scores, thumbs up/down, or notes to spans for RLHF and evaluation workflows.
+- **Enrich trace context**: Add custom events and notes to spans for richer debugging.
 
 ---
 
 ## How to
 
 <Steps>
   <Step title="Create an annotation label">
-    Annotation labels must be created in the UI before you can use them in the API.
-
-    - Go to your project in Observe/Prototype.
-    - Click on any Trace or Span to open the Trace Details page.
-    - Click on the "Annotations" tab.
-    - Click on the "Create Annotation Label" button.
-    - Fill in the form with the following information:
-      - Name: The name of the annotation label.
-      - Description: The description of the annotation label.
-      - Type: The type of the annotation label.
-        - `Text`: this type is used for free text annotations.
-        - `Numeric`: this type is used for numeric annotations.
-        - `Categorical`: this type is used for categorical annotations.
-        - `Star`: this type is used for star rating annotations.
-        - `Thumbs up/down`: this type is used for thumbs up/down annotations.
-    - Write the necessary configuration for the annotation label.
-    - Click on the "Create" button.
-    - You will be redirected to the Annotation Labels page.
-    - You can see the created annotation label in the list.
-    - You can edit the annotation label by clicking on the "Edit" button.
-    - You can delete the annotation label by clicking on the "Delete" button.
-
-    ![Annotations Tab](/images/docs/observe/features/manual-tracing/annotations_tab.png)
+    Annotation labels must be created before using the API. See the [Labels guide](/docs/annotations/features/labels) for how to create and configure labels (text, numeric, categorical, star, thumbs up/down).
   </Step>
 
   <Step title="Fetch your annotation label ID">
@@ -205,7 +185,7 @@ Looking for the new unified Annotations system? Check out the [Annotations docum
         pretty(resp.json())
     ```
 
-    ```typescript Typescript
+    ```javascript JS/TS
     #!/usr/bin/env ts-node
     import axios from "axios";
 
@@ -322,17 +302,9 @@ Each element in `result.errors` contains:
 | annotationError | string | "Annotation label \"axdf\" does not belong to span's project" | Error message for the annotation operation (optional). |
 | noteError | string | "Duplicate note" | Error message for the note operation (optional). |
 
-**Best practices**
-
-- **Immutable labels** — avoid changing the meaning of an existing label; create a new one instead.
-- **Consistent annotator IDs** — use stable identifiers (`"human_annotator_1"`, `"model_v1"`, …).
-- **Batch updates** — updating many spans? Group 100–500 records per request to minimize network overhead.
-- **Idempotency** — sending the same note text twice in a record skips duplicates, keeping data clean.
-- **Monitor quotas** — large annotation operations count toward your project's API usage.
-
 ---
 
-## What you can do next
+## Next Steps
 
 <CardGroup cols={2}>
   <Card title="Set Up Tracing" icon="gear" href="/docs/observe/features/manual-tracing/set-up-tracing">