# Score Writing

{% hint style="info" %}
This features requires a Premium Subscription

**Run in postman:** [Score Writing](https://docs.speechace.com/#b21cde34-7649-450a-ae0e-dabee579d1f3)
{% endhint %}

The Score Writing API evaluates 3 different writing tasks and returns scores aligned with CEFR, IELTS, PTE, and the Speechace rubrics.

<table><thead><tr><th width="142.4140625">Task</th><th width="100">Length</th><th>Description</th></tr></thead><tbody><tr><td>essay-writing</td><td>150 - 300 words</td><td>Long form opinion-based writing such as IELTS Task 2 writing prompts.</td></tr><tr><td>short-writing</td><td>50 - 100 words</td><td>Short form school or business writing such as describing an image, or writing a short letter.</td></tr><tr><td>chat-writing</td><td>50 - 100 words</td><td>Brief responses to a query or situation expressed in a chat context. Suitable for business contexts such as customer support simulation.</td></tr></tbody></table>

The Score Writing API is available in the following languages:

* English (en-us, en-gb)
* Spanish (es-es)

The Score Writing API returns scores in the following formats:

* Speechace scale (0..100)
* CEFR scale (A0..C2)
* IELTS scale (0..9)
* PTE scale (10..90)
* TOEIC scale (0..200)

### Request Format&#x20;

The endpoint that is to be used will depend on the [region](/getting-started/pre-requisites/api-regions-and-endpoints.md) of your subscription. For example, for US West, the endpoint is <https://api.speechace.co>.

`POST` [`https://api.speechace.co/api/scoring/writing/v9/json`](https://api.speechace.co/api/scoring/writing/v9/json)

### Query Parameters

<table><thead><tr><th width="136">Parameter</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>key</td><td>String</td><td><strong>Required:</strong> <em>API</em> <a href="/pages/FY5QJQ5NVDkUtPtG080s"><em>key</em></a> <em>issued by Speechace.</em></td></tr><tr><td>dialect</td><td>String</td><td><p><strong>Optional:</strong> default = en-us </p><p><em>This is the</em> <a href="/pages/PM2D802SgqeoWM8lrey5"><em>dialect</em></a> <em>in which the writing sample will be assessed.</em></p><p><em>Supported values are: <code>en-us</code>, <code>en-gb</code>, <code>es-es</code>.</em></p></td></tr><tr><td>user_id</td><td>String</td><td><em><strong>Optional</strong>: A unique anonymized identifier (generated by your applications) for the end-user who submitted the response.</em></td></tr><tr><td>task_type</td><td>String</td><td><p><em>The writing task_type to score. Supported types are:</em></p><p></p><ul><li><em>essay-writing</em></li><li><em>short-writing</em></li><li><em>chat-writing</em></li></ul></td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="169">Parameter</th><th width="100">Type</th><th>Description</th></tr></thead><tbody><tr><td>prompt</td><td>String</td><td><p><strong>Required:</strong> Max 2048 chars</p><p>The writing task prompt given to the end-user.</p></td></tr><tr><td>answer</td><td>String</td><td><p><strong>Required:</strong> Max 4096 chars</p><p>The response submitted by the end-user which will be scored in context of the prompt.</p></td></tr><tr><td>include_feedback</td><td>String</td><td><p><strong>Optional:</strong> 0 | 1, default = 0<br>Indicates whether to return additional feedback also as part of the API response.</p><p><br><span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span><strong>Warning:</strong> This field has a cost and performance impact. Use only when needed and avoid making the default on all requests.</p></td></tr><tr><td>detect_dialect</td><td>String</td><td><p><strong>Optional:</strong> 0 | 1, default = 0</p><p>Indicates whether to return detected dialect of the user response as part of of the API response.</p></td></tr><tr><td>enforce_dialect</td><td>String</td><td><p><strong>Optional:</strong> 0 | 1, default = 0</p><p>Indicates whether to enforce detected dialect of the user response be same as dialect of the calling API i.e. raises error if the user response dialect doesn't match expected dialect.</p></td></tr><tr><td>include_metrics</td><td>String</td><td><p><strong>Optional:</strong> array of string enums, default = []</p><p>Indicates which metrics to use for score. The list of enum values are: <code>vocab</code>, <code>grammar</code>, <code>coherence</code>, <code>task_response</code>. default of [] indicates all metrics to score.</p></td></tr><tr><td>score_mode</td><td>String</td><td><strong>Optional:</strong><br>default: default scoring mode (balances accuarcy, performance, and cost)<br>enhanced: enhanced scoring mode (higher accuracy model with also higher compute and cost impact)</td></tr></tbody></table>

### Response Examples

The `writing_score.speechace.overall` key contrains the overall writing score in the Speechace numerical scale (0..100). The overall score is the average of 4 sub-scores:

* `writing_score.speechace.task_response`&#x20;
* `writing_score.speechace.grammar`&#x20;
* `writing_score.speechace.vocab`&#x20;
* `writing_score.speechace.coherence`&#x20;

{% hint style="info" %}
Refer to the [Writing Score Rubric guide](/guides-on-common-topics/interpreting-writing-scores/writing-scoring-rubrics.md) for interpreting the scores.
{% endhint %}

{% tabs %}
{% tab title="essay-writing" %}
{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "request_id": "8bf1ccf7d5225aaccb35f80acdacd5a6",
  "status": "success",
  "task_type": "essay-writing",
  "task_version": "0.1",
  "answer": "Some people insist that volunteer services like charity activity should be introduced to the high school curriculum, whereas others think it should not be treated as part of mandatory education. Nonetheless, I personally lean more toward the latter view, simply because the level of benefits is heavily affected by the individual point of view or circumstance.\n\nThere are several cases that unpaid service would be beneficial. For instance, they would be able to develop a sense of community or meet new people regardless of their individual skill or aptitude. According to a research paper issued by Cambridge University last year, the majority of successful people in business intentionally participate some volunteer activity at an early age in order to create connections for the future. Considering that childhood is a preparation period for a member of society, it is no doubt providing them such opportunities are more practical and fruitful idea.\n\nTurning to the other side of the argument, it could be acknowledged as a just hindrance for achieving an individual goal. Firstly, for the people who are considering to go to the university as their future plan, their top priority may not make  connections but building up academic knowledge or conquering examination. Secondly, there might be students who dedicate their time for part-time job to set aside money as a tuition fee or provide their family. From their point of view, volunteer work is just wasting their time and not necessarily essential. \n\nIn conclusion, while some people say imposing unpaid service for high school students is significant, we cannot ignore the fact that it has not only a positive aspect but also a negative side. I believe that as long as it has some drawbacks, it should not be a compulsory subject and needlessly deprive student's precious time.",
  "char_count": 1840,
  "writing_score": {
    "speechace": {
      "task_response": 78,
      "vocab": 78,
      "coherence": 78,
      "grammar": 72,
      "overall": 78
    },
    "ielts": {
      "task_response": 7,
      "vocab": 7,
      "coherence": 7,
      "grammar": 6.5,
      "overall": 7
    },
    "cefr": {
      "task_response": "B2+",
      "vocab": "B2+",
      "coherence": "B2+",
      "grammar": "B2",
      "overall": "B2+"
    },
    "pte": {
      "task_response": 66,
      "vocab": 66,
      "coherence": 66,
      "grammar": 56,
      "overall": 66
    },
    "toeic": {
      "task_response": 160,
      "vocab": 160,
      "coherence": 160,
      "grammar": 140,
      "overall": 160
    }
  },
  "version": "9.14"
}
```

{% endcode %}
{% endtab %}

{% tab title="short-writing" %}
{% code overflow="wrap" lineNumbers="true" %}

```json
{
  "request_id": "cc387bb553cbd4444fd0942b84b1a6ea",
  "status": "success",
  "task_type": "short-writing",
  "task_version": "0.1",
  "answer": "Last week I went to Hawaii with my family.It was good,first I go to swim on the ocean it was the best of my vacations ,but then I see lots of fishes on the ocean they were beutiful and they swim so fast.My dad talk me that the fishes were so fast because they has to swim from they born and if they do not swim fast the sharks eats them.It was all beutiful and interesting.That was my best vacations of all.",
  "char_count": 407,
  "writing_score": {
    "speechace": {
      "task_response": 44,
      "vocab": 33,
      "coherence": 28,
      "grammar": 22,
      "overall": 33
    },
    "ielts": {
      "task_response": 4,
      "vocab": 3,
      "coherence": 2.5,
      "grammar": 2,
      "overall": 3
    },
    "cefr": {
      "task_response": "A2+",
      "vocab": "A2+",
      "coherence": "A2",
      "grammar": "A2",
      "overall": "A2+"
    },
    "pte": {
      "task_response": 20,
      "vocab": 15,
      "coherence": 12,
      "grammar": 10,
      "overall": 15
    },
    "toeic": {
      "task_response": 50,
      "vocab": 30,
      "coherence": 30,
      "grammar": 20,
      "overall": 30
    }
  },
  "version": "9.14"
}
```

{% endcode %}
{% endtab %}

{% tab title="chat-writing" %}

```json
{
  "request_id": "2350acdfee234783d2746e297fb18d13",
  "status": "success",
  "task_type": "chat-writing",
  "task_version": "0.1",
  "answer": "I am really sorry to hear about your experience. Let me help you address this right away. I will need your order details and a description of the damage, and then I will immediately send you a replacement item. If you prefer a refund, please let me know. Finally, we will also send you instructions on how to return the damaged item.\nWe apologize for this experience and hope to immediately rectify it.",
  "char_count": 402,
  "writing_score": {
    "speechace": {
      "task_response": 78,
      "vocab": 78,
      "coherence": 83,
      "grammar": 78,
      "overall": 83
    },
    "ielts": {
      "task_response": 7,
      "vocab": 7,
      "coherence": 7.5,
      "grammar": 7,
      "overall": 7.5
    },
    "cefr": {
      "task_response": "B2+",
      "vocab": "B2+",
      "coherence": "C1",
      "grammar": "B2+",
      "overall": "C1"
    },
    "pte": {
      "task_response": 66,
      "vocab": 66,
      "coherence": 76,
      "grammar": 66,
      "overall": 76
    },
    "toeic": {
      "task_response": 160,
      "vocab": 160,
      "coherence": 170,
      "grammar": 160,
      "overall": 170
    }
  },
  "version": "9.14"
}
```

{% endtab %}

{% tab title="short-writing w/ feedback" %}

```json
{
  "request_id": "9250948130c4e9e4c16567a995cc37e9",
  "status": "success",
  "task_type": "short-writing",
  "task_version": "0.1",
  "answer": "Last week I went to Hawaii with my family.It was good,first I go to swim on the ocean it was the best of my vacations ,but then I see lots of fishes on the ocean they were beutiful and they swim so fast.My dad talk me that the fishes were so fast because they has to swim from they born and if they do not swim fast the sharks eats them.It was all beutiful and interesting.That was my best vacations of all.",
  "char_count": 407,
  "writing_score": {
    "speechace": {
      "task_response": 44,
      "vocab": 28,
      "coherence": 28,
      "grammar": 22,
      "overall": 33
    },
    "ielts": {
      "task_response": 4,
      "vocab": 2.5,
      "coherence": 2.5,
      "grammar": 2,
      "overall": 3
    },
    "cefr": {
      "task_response": "A2+",
      "vocab": "A2",
      "coherence": "A2",
      "grammar": "A2",
      "overall": "A2+"
    },
    "pte": {
      "task_response": 20,
      "vocab": 12,
      "coherence": 12,
      "grammar": 10,
      "overall": 15
    },
    "toeic": {
      "task_response": 50,
      "vocab": 30,
      "coherence": 30,
      "grammar": 20,
      "overall": 30
    }
  },
  "feedback": {
    "vocab": [
      {
        "category": "Redundancy and Tautology",
        "original_phrase": "first I go to swim on the ocean",
        "replacement_phrase": "first I went swimming in the ocean",
        "rationale": "Avoid redundancy and use a more concise and accurate phrase.",
        "span": [
          54,
          84
        ],
        "replacements": [
          {
            "span": [
              62,
              73
            ],
            "text": "go to swim o",
            "type": "omission"
          },
          {
            "span": [
              74,
              74
            ],
            "text": "went swimming i",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Word Appropriateness",
        "original_phrase": "vacations",
        "replacement_phrase": "vacation",
        "rationale": "The correct term is 'vacation' when referring to a single trip.",
        "span": [
          108,
          116
        ],
        "replacements": [
          {
            "span": [
              116,
              116
            ],
            "text": "s",
            "type": "omission"
          }
        ]
      },
      {
        "category": "Word Appropriateness",
        "original_phrase": "vacations",
        "replacement_phrase": "vacation",
        "rationale": "Use the singular form 'vacation' for consistency.",
        "span": [
          108,
          116
        ],
        "replacements": [
          {
            "span": [
              116,
              116
            ],
            "text": "s",
            "type": "omission"
          }
        ]
      },
      {
        "category": "Redundancy and Tautology",
        "original_phrase": "but then I see lots of fishes on the ocean",
        "replacement_phrase": "but then I saw many fish in the ocean",
        "rationale": "Use the singular 'fish' instead of 'fishes' and improve clarity.",
        "span": [
          119,
          160
        ],
        "replacements": [
          {
            "span": [
              131,
              140
            ],
            "text": "ee lots of",
            "type": "omission"
          },
          {
            "span": [
              141,
              141
            ],
            "text": "aw many",
            "type": "insertion"
          },
          {
            "span": [
              146,
              149
            ],
            "text": "es o",
            "type": "omission"
          },
          {
            "span": [
              150,
              150
            ],
            "text": " i",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Word Appropriateness",
        "original_phrase": "beutiful",
        "replacement_phrase": "beautiful",
        "rationale": "Correct the spelling of 'beautiful'.",
        "span": [
          172,
          179
        ],
        "replacements": [
          {
            "span": [
              174,
              174
            ],
            "text": "a",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Word Appropriateness",
        "original_phrase": "beutiful",
        "replacement_phrase": "beautiful",
        "rationale": "Correct the spelling of 'beautiful'.",
        "span": [
          172,
          179
        ],
        "replacements": [
          {
            "span": [
              174,
              174
            ],
            "text": "a",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Precision and Nuance",
        "original_phrase": "My dad talk me that the fishes were so fast because they has to swim from they born",
        "replacement_phrase": "My dad explained that the fish swim fast because they need to swim from birth",
        "rationale": "Clarify the explanation and use correct verb tenses.",
        "span": [
          203,
          285
        ],
        "replacements": [
          {
            "span": [
              210,
              216
            ],
            "text": "talk me",
            "type": "omission"
          },
          {
            "span": [
              217,
              217
            ],
            "text": "explained",
            "type": "insertion"
          },
          {
            "span": [
              231,
              240
            ],
            "text": "es were so",
            "type": "omission"
          },
          {
            "span": [
              241,
              241
            ],
            "text": " swim",
            "type": "insertion"
          },
          {
            "span": [
              260,
              262
            ],
            "text": "has",
            "type": "omission"
          },
          {
            "span": [
              263,
              263
            ],
            "text": "need",
            "type": "insertion"
          },
          {
            "span": [
              277,
              285
            ],
            "text": "they born",
            "type": "omission"
          },
          {
            "span": [
              286,
              286
            ],
            "text": "birth",
            "type": "insertion"
          }
        ]
      }
    ],
    "coherence": [
      {
        "category": "Logical Progression of Ideas",
        "original_phrase": "first I go to swim on the ocean it was the best of my vacations ,but then I see lots of fishes on the ocean they were beutiful and they swim so fast.",
        "replacement_phrase": "First, I went swimming in the ocean. It was the highlight of my vacation. I saw many beautiful and fast-swimming fishes.",
        "rationale": "The revised sentence provides a clearer and more organized sequence of events, improving the logical progression of ideas.",
        "span": [
          54,
          202
        ],
        "replacements": [
          {
            "span": [
              54,
              54
            ],
            "text": "f",
            "type": "omission"
          },
          {
            "span": [
              55,
              55
            ],
            "text": "F",
            "type": "insertion"
          },
          {
            "span": [
              59,
              59
            ],
            "text": ",",
            "type": "insertion"
          },
          {
            "span": [
              62,
              73
            ],
            "text": "go to swim o",
            "type": "omission"
          },
          {
            "span": [
              74,
              74
            ],
            "text": "went swimming i",
            "type": "insertion"
          },
          {
            "span": [
              85,
              86
            ],
            "text": " i",
            "type": "omission"
          },
          {
            "span": [
              87,
              87
            ],
            "text": ". I",
            "type": "insertion"
          },
          {
            "span": [
              97,
              99
            ],
            "text": "bes",
            "type": "omission"
          },
          {
            "span": [
              100,
              100
            ],
            "text": "highligh",
            "type": "insertion"
          },
          {
            "span": [
              116,
              170
            ],
            "text": "s ,but then I see lots of fishes on the ocean they were",
            "type": "omission"
          },
          {
            "span": [
              171,
              171
            ],
            "text": ". I saw many",
            "type": "insertion"
          },
          {
            "span": [
              174,
              174
            ],
            "text": "a",
            "type": "insertion"
          },
          {
            "span": [
              185,
              201
            ],
            "text": "they swim so fast",
            "type": "omission"
          },
          {
            "span": [
              202,
              202
            ],
            "text": "fast-swimming fishes",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Effective Use of Linking Words",
        "original_phrase": "My dad talk me that the fishes were so fast because they has to swim from they born and if they do not swim fast the sharks eats them.",
        "replacement_phrase": "My dad explained to me that the fishes were fast because they have to swim from birth, and if they don't swim fast, the sharks will eat them.",
        "rationale": "The replacement phrase uses appropriate linking words ('explained,' 'because,' 'and'), making the connection between ideas clearer and improving the flow of the sentence.",
        "span": [
          203,
          336
        ],
        "replacements": [
          {
            "span": [
              210,
              213
            ],
            "text": "talk",
            "type": "omission"
          },
          {
            "span": [
              214,
              214
            ],
            "text": "explained to",
            "type": "insertion"
          },
          {
            "span": [
              239,
              241
            ],
            "text": "so ",
            "type": "omission"
          },
          {
            "span": [
              262,
              262
            ],
            "text": "s",
            "type": "omission"
          },
          {
            "span": [
              263,
              263
            ],
            "text": "ve",
            "type": "insertion"
          },
          {
            "span": [
              277,
              285
            ],
            "text": "they born",
            "type": "omission"
          },
          {
            "span": [
              286,
              286
            ],
            "text": "birth,",
            "type": "insertion"
          },
          {
            "span": [
              301,
              303
            ],
            "text": " no",
            "type": "omission"
          },
          {
            "span": [
              304,
              304
            ],
            "text": "n'",
            "type": "insertion"
          },
          {
            "span": [
              315,
              315
            ],
            "text": ",",
            "type": "insertion"
          },
          {
            "span": [
              327,
              327
            ],
            "text": "will ",
            "type": "insertion"
          },
          {
            "span": [
              330,
              330
            ],
            "text": "s",
            "type": "omission"
          }
        ]
      },
      {
        "category": "Focus and Relevance within Paragraph",
        "original_phrase": "It was all beutiful and interesting.",
        "replacement_phrase": "The experience was both beautiful and fascinating.",
        "rationale": "The revised phrase maintains the positive sentiment while providing a more focused and concise description of the experience.",
        "span": [
          337,
          372
        ],
        "replacements": [
          {
            "span": [
              337,
              338
            ],
            "text": "It",
            "type": "omission"
          },
          {
            "span": [
              339,
              339
            ],
            "text": "The experience",
            "type": "insertion"
          },
          {
            "span": [
              344,
              346
            ],
            "text": "all",
            "type": "omission"
          },
          {
            "span": [
              347,
              347
            ],
            "text": "both",
            "type": "insertion"
          },
          {
            "span": [
              350,
              350
            ],
            "text": "a",
            "type": "insertion"
          },
          {
            "span": [
              361,
              367
            ],
            "text": "interes",
            "type": "omission"
          },
          {
            "span": [
              368,
              368
            ],
            "text": "fascina",
            "type": "insertion"
          }
        ]
      }
    ],
    "grammar": [
      {
        "category": "Subject-Verb Agreement",
        "original_phrase": "first I go to swim on the ocean",
        "replacement_phrase": "first I went swimming in the ocean",
        "rationale": "Subject-verb agreement between 'I' and 'went'",
        "span": [
          54,
          84
        ],
        "replacements": [
          {
            "span": [
              62,
              73
            ],
            "text": "go to swim o",
            "type": "omission"
          },
          {
            "span": [
              74,
              74
            ],
            "text": "went swimming i",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Verb Tense Consistency",
        "original_phrase": "but then I see lots of fishes on the ocean",
        "replacement_phrase": "but then I saw lots of fishes in the ocean",
        "rationale": "Maintaining past tense consistency",
        "span": [
          119,
          160
        ],
        "replacements": [
          {
            "span": [
              131,
              132
            ],
            "text": "ee",
            "type": "omission"
          },
          {
            "span": [
              133,
              133
            ],
            "text": "aw",
            "type": "insertion"
          },
          {
            "span": [
              149,
              149
            ],
            "text": "o",
            "type": "omission"
          },
          {
            "span": [
              150,
              150
            ],
            "text": "i",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Verb Tense Consistency",
        "original_phrase": "My dad talk me that the fishes were so fast",
        "replacement_phrase": "My dad told me that the fishes were so fast",
        "rationale": "Maintaining past tense consistency",
        "span": [
          203,
          245
        ],
        "replacements": [
          {
            "span": [
              211,
              213
            ],
            "text": "alk",
            "type": "omission"
          },
          {
            "span": [
              214,
              214
            ],
            "text": "old",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Subject-Verb Agreement",
        "original_phrase": "they has to swim from they born",
        "replacement_phrase": "they have to swim from birth",
        "rationale": "Subject-verb agreement between 'they' and 'have'",
        "span": [
          255,
          285
        ],
        "replacements": [
          {
            "span": [
              262,
              262
            ],
            "text": "s",
            "type": "omission"
          },
          {
            "span": [
              263,
              263
            ],
            "text": "ve",
            "type": "insertion"
          },
          {
            "span": [
              277,
              285
            ],
            "text": "they born",
            "type": "omission"
          },
          {
            "span": [
              286,
              286
            ],
            "text": "birth",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Articles and Determiners",
        "original_phrase": "It was all beutiful and interesting",
        "replacement_phrase": "It was all beautiful and interesting",
        "rationale": "Correcting the spelling of 'beautiful' and adding the article 'a' before 'beautiful'",
        "span": [
          337,
          371
        ],
        "replacements": [
          {
            "span": [
              350,
              350
            ],
            "text": "a",
            "type": "insertion"
          }
        ]
      },
      {
        "category": "Verb Tense Consistency",
        "original_phrase": "That was my best vacations of all",
        "replacement_phrase": "That was my best vacation ever",
        "rationale": "Maintaining past tense consistency and correcting the plural form of 'vacations' to singular 'vacation'",
        "span": [
          373,
          405
        ],
        "replacements": [
          {
            "span": [
              398,
              405
            ],
            "text": "s of all",
            "type": "omission"
          },
          {
            "span": [
              406,
              406
            ],
            "text": " ever",
            "type": "insertion"
          }
        ]
      }
    ]
  },
  "version": "9.14"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Which writing task\_type should I use?**

Here is when to use each task\_type:

If the writing is an essay and at least 150 words, then use essay-writing. If it's general and less than 150 words, then use short-writing. If the prompt contains a chat scenario with the user expected to respond to a question or situation, then use chat-writing.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.speechace.com/api-reference/score-writing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.