Təlimatlardan tools və metadata dizaynına: discovery və marşrutlaşdırma

1. Yaxşı tools və metadata olmadan təkcə təlimatlar niyə kifayət etmir

Bir xoşagəlməz həqiqəti vurğulamaq vacibdir: model sizin kodu görmür. O, Next.js-də hansı controller-lərin, TypeScript-də hansı funksiyaların olduğunu və tövsiyə xidmətində yığdığınız gözəl evristikaları bilmir.

O, App-ınızı bir neçə interfeys vasitəsilə görür:

1. System‑prompt (rol müqaviləsi).
2. Alətlərin təsviri: ad, description, inputSchema, outputSchema, annotasiyalar və s.
3. Tətbiqin öz metadatasi: ad, ikon, qısa və uzun təsvir, kateqoriyalar, conversation starters və s.

Sorğunu emal edərkən model dialoq kontekstinə və bu metadatasına baxır ki, qərar versin:

• ümumiyyətlə hansısa App təklif etmək lazımdırmı;
• əgər bəli — mövcudlardan konkret hansını;
• və App seçilibsə — həmin App-ın hansı aləti cari sorğuya uyğundur.

Modul 5-in əvvəlki hissəsində modeli sözlərlə “nəql edə” biləcəyimiz şeylərlə məşğul olduq — system‑prompt və UX təlimatları. İndi isə mətndən əlavə nə gördüyünə keçirik: tools və metadata.

Ona görə də Modul 5-in vəzifəsi əslində ikilidir. Əvvəlcə system‑prompt-da “bu App nə etməli və necə davranmalıdır”ı formalaşdırırsınız, sonra isə tools və metadatanın dizaynında bunu modelin həqiqətən istifadə edə bildiyi formaya qablaşdırırsınız — discovery və marşrutlaşdırma üçün də.

Özünüz üçün belə ifadə edə bilərsiniz: system‑prompt — konstitusiyadır, tools və metadata isə artıq qanunlar və ətrafındakı bürokratiyadır: ərizə formaları, verilənlər bazası sxemləri və s. Təkcə konstitusiya ilə məhdudlaşsaq, uzağa gedə bilməyəcəyik.

2. Dekompozisiya: “bir vəzifə — bir tool”, amma ağlabatan

Ən ağrılı yerdən başlayaq: ümumiyyətlə neçə alət hazırlamalı və onları necə bölməli.

İntuitiv prinsip: bir alət — bir anlaşılan vəzifə. Bu, model üçün seçimi xeyli asanlaşdırır: onun 1 monstr funksiyası do_everything deyil, yaxşı adlara malik bir neçə səliqəli hərəkəti olur.

GiftGenius üçün belə baza alətləri ola bilər:

• profile_to_segments — alıcının sərbəst təsvirini (yaş, maraqlar, münasibət, kontekst) "tech", "fitness", "gamer" kimi normallaşdırılmış segmentlərə çevirmək.
• recommend_gifts — segmentlərə, büdcəyə, lokaleyə və səbəbə görə hədiyyə id-lərinin siyahısını seçmək.
• get_gift — seçilmiş hədiyyənin id-si üzrə tam kartını (təsvir, media, SKU/variasiyalar) əldə etmək.
• (opsional) similar_gifts — seçilmiş hədiyyə əsasında daha 3–5 oxşar variant təklif etmək.

Teorik olaraq gift_tool adlı bir alət yaradıb mode: "profile_to_segments" | "recommend" | "details" | "similar" parametrindən istifadə etmək olardı, amma bu halda həm özünüzün, həm də modelin işini çətinləşdirirsiniz: təsvir kağız-kimi uzanır, inputSchema şişir, alət seçərkən modelin daha az dəqiq ankirləri qalır.

Anti‑pattern: God Tool

Belə bir sxemi təsəvvür edin:

server.registerTool(
  "gift_tool",
  {
    description: "Hədiyyələrlə müxtəlif əməliyyatlar.",
    inputSchema: { /* 50 sahə və bayraq */ },
  },
  async ({ input }) => { /* mode üzrə böyük switch */ }
);

Modelin beynində bu, “hədiyyələr haqqında hansısa abstrakt alət var, sonrası gələrik” kimi görünür. Bu, seçimin dəqiqliyini pisləşdirir, discovery-yə mane olur və sizin üçün müşayiəti çətinləşdirir.

Amma digər ifrata düşmək — hər xırda şey üçün 50 mikroskopik alət düzəltmək — də pisdir. Hər əlavə alət kontekstə düşür, modelin diqqətini yükləyir və marşrutlaşdırma səhvlərinin riskini artırır. Sənədləşmə açıq xəbərdar edir: çox xırda alətlər keyfiyyətə mənfi təsir göstərir, xüsusən də onların təsvirləri bir-birini kəsəndə.

İstifadəsi rahat praktiki qayda:

• istifadəçinin ssenaridə bir “addım” kimi qəbul etdiyi hər şey (məsələn, profil üzrə ilk hədiyyə seçimi) — ayrı tool üçün yaxşı namizəddir;
• həmin addımın daxilində həmişə həyata keçirilən və müstəqil mənası olmayan şeylər (məsələn, skorun hesablanması və ya kartların baxışının loglanması) alətin implementasiyasının içində qalmalıdır.

Güman ki, bu prinsip üzrə ssenariləri artıq 2–4 alətə böldünüz. Növbəti vacib sual — bu tools-un girişlərini elə necə təsvir edək ki, model onlardan gümanlara girmədən istifadə edə bilsin. Elə bununla başlayaq.

3. Use‑case-ləri Input Schema-ya proyeksiya edirik

İndi konkret bir use‑case götürüb səmimi baxırıq: alətə həqiqətən hansı məlumatlar lazımdır.

Ssenari: “Hədiyyə verən deadline-dadır: 25 yaşlı, futbolu və stolüstü oyunları sevən dost üçün 5–7 ideya seç, büdcə $50-a qədər”.

Jobs‑to‑be‑done-dan aydındır ki, GiftGenius-un tövsiyəedici nüvəsinin vəzifəsi seçimi kiçik bir siyahıya qədər daraltmaq və “birdən mən pis bir şey seçərəm” narahatlığını azaltmaqdır. Çat səviyyəsində asistentin ehtiyacı olanlar:

• alıcı haqqında baza məlumat (yaş, cins, hədiyyə verənlə münasibət);
• maraqlar/hobbilər;
• büdcə və valyuta;
• səbəb (ad günü, yubiley, Yeni il və s.);
• opsional — çatdırılma filtrinə görə ölkə/şəhər.

GiftGenius arxitekturasında bu iki addıma bölünüb:

1. profile_to_segments(input) “xam” məlumatları (yaş, maraqlar, mətndəki təsvir) qəbul edir və onları növbəti mərhələdə rahat işləmək üçün normallaşdırılmış segmentlərə çevirir.
2. recommend_gifts(segments, budget, locale, occasion) artıq segmentlər və büdcə üzrə kataloqdan konkret hədiyyə id-lərini seçir.

ChatGPT ↔ MCP müqaviləsi baxımından məhz ikinci addımı — recommend_gifts-in sxemini təsvir etmək vacibdir, çünki seçimin çoxu bu alətdən istifadə edəcək ssenarilərlə gedir.

Bununla belə, istifadəçidən hər şeyi dərhal tələb etmək lazım deyil: model follow‑up vasitəsilə bir hissəni dəqiqləşdirə bilər (“təxminən hansı büdcə?”). Deməli, profilin bəzi sahələri opsional ola bilər; amma recommend_gifts-ə çatanda artıq normallaşdırılmış parametr dəsti olmalıdır.

Nümunə: recommend_gifts üçün TypeScript + JSON Schema

MCP serverində TypeScript ilə bu belə görünə bilər:

// apps/mcp/server.ts
import { McpServer } from "@openai/mcp-server";

const server = new McpServer();

server.registerTool(
  "recommend_gifts",
  {
    title: "Hədiyyə tövsiyələri",
    description:
      "Bu aləti alıcının segmentlərinə, büdcəyə, lokaleyə və səbəbə görə hədiyyələr seçmək lazım olduqda istifadə et.",
    inputSchema: {
      type: "object",
      properties: {
        segments: {
          type: "array",
          description:
            "Alıcının segmentləri siyahısı, məsələn ['tech', 'football_fan']. Adətən profile_to_segments-dən götürülür.",
          items: { type: "string" },
          minItems: 1
        },
        budget: {
          type: "object",
          description:
            "İstifadəçinin valyutasında hədiyyə üçün büdcə diapazonu (minimum/maksimum).",
          properties: {
            min: {
              type: "number",
              minimum: 0,
              description: "İstifadəçinin xərcləməyə hazır olduğu minimum məbləğ."
            },
            max: {
              type: "number",
              minimum: 0,
              description: "İstifadəçinin xərcləməyə hazır olduğu maksimum məbləğ."
            },
            currency: {
              type: "string",
              minLength: 3,
              maxLength: 3,
              description: "Üçhərfəli valyuta kodu (məsələn, USD, EUR, RUB)."
            }
          },
          required: ["min", "max", "currency"]
        },
        locale: {
          type: "string",
          description:
            "İstifadəçinin lokaleyi BCP‑47 formatında (məsələn, 'ru-RU' və ya 'en-US')."
        },
        occasion: {
          type: "string",
          description:
            "Hədiyyə üçün səbəb, məsələn 'birthday', 'new_year', 'anniversary'."
        }
      },
      required: ["segments", "budget", "locale", "occasion"]
    }
  },
  async ({ input }) => {
    // Hələ ağıllı işləmirik, müvəqqəti stub qaytarırıq
    return {
      content: [
        {
          type: "text",
          text: `Segmentlər üzrə hədiyyələr seçirəm ${input.segments?.join(
            ", "
          )} büdcə çərçivəsində ${input.budget?.min}–${input.budget?.max} ${input.budget?.currency}...`
        }
      ],
      structuredContent: {}
    };
  }
);

Bir neçə məqama diqqət edin.

Birincisi, enum-abid məhdudiyyətlərdən və anlaşılan təsvirlərdən aktiv istifadə edirik. Formal olaraq bunlar sadəcə sətirlər olsa da, description modelə hansı dəyərlərin gözlənildiyini bildirir və arqumentləri düzgün doldurma ehtimalını nəzərəçarpacaq dərəcədə artırır. Yayğın "səbəb": "nəsə ad gününə bənzər" sətiri əvəzinə səliqəli occasion: "birthday" var.

İkincisi, sahələrin təsvirləri “komandadakı insanlar üçün” deyil, məhz model üçün ipucu kimi yazılır: bu sahə nədir, tipik dəyərlər hansılardır, nümunə varmı. Apps SDK sənədlərinin müəllifləri hər parametr üçün insan başa düşən descriptions və nümunələr əlavə etməyi birbaşa tövsiyə edirlər.

Giriş sxemində nə olmamalıdır

Tez-tez ora salınmağa çalışılan tipik parazit sahələr:

• daxili identifikatorlar (tenantId, internalSegment), bunları serverdə özünüz əlavə edə bilərsiniz;
• modelin heç cür bilməyəcəyi şeylər (məsələn, deploymentRegion) — bu artıq sizin məsuliyyət sahənizdir;
• çat tarixçəsinin dublikatı olan sahələr (məsələn, userPrompt): model onsuz da ilkin mesajı görür, onu copy‑paste etdirməyin.

Input Schema — modelin qərar verib doldurmalı olduğu hissədir, ümumi hər şey kisəsi deyil.

4. Output Schema: təkcə məlumat yox, həm də məna

Apps SDK-da alətin nəticəsi dialoqa role: tool mesajı kimi qayıdır. Sonra artıq model qərar verir ki, bununla nə etsin: cavabı necə tərtib etsin, hansı follow‑up suallar versin, vidjeti açmaq lazımdırmı və s. Buna görə də çıxış sxeminin dizaynı girişdən az önəmli deyil.

İki yanaşma var.

“Xam məlumatlar” varianti belə görünür:

{
  "items": [
    { "id": "GIFT_1" },
    { "id": "GIFT_2" }
  ]
}

Model sadəcə id-lər siyahısını görür, niyə bu variantların burada olduğunu, neçə namizəd olduğunu və hansının ən yaxşısı olduğunu anlamır. Nəsə uydura bilər, amma qəribəlik ehtimalı daha yüksəkdir.

Semantik cəhətdən zəngin variant:

{
  "items": [
    {
      "id": "GIFT_1",
      "score": 0.92,
      "reason": "“football_fan” segmenti ilə güclü uyğunlaşır və büdcəyə sığır."
    },
    {
      "id": "GIFT_2",
      "score": 0.81,
      "reason": "Stolüstü oyunları sevənlər üçün uyğundur, büdcənin yuxarı həddinə daha yaxındır."
    }
  ],
  "meta": {
    "totalCandidates": 27,
    "returned": 5,
    "segmentsUsed": ["football_fan", "board_games"],
    "budget": { "min": 20, "max": 50, "currency": "USD" },
    "advice": "Ən yüksək score olan və aydın izahlı variantlardan başlamaq daha yaxşıdır."
  }
}

İndi model dürüstcə izah edə bilər ki, niyə məhz bu hədiyyələr seçildi və follow‑up qura bilər: “27 variant tapdım, 5 ən yaxşısını göstərirəm, səbəbləri bunlardır”.

Nümunə: recommend_gifts üçün Output Schema-nı təsvir edirik

Alətin təsvirinə nəticə sxemini əlavə edək (texniki cəhətdən göstərmədən də olar, amma bunu etmək daha yaxşıdır — bu, model ilə müqavilənin bir hissəsidir):

const recommendGiftsOutputSchema = {
  type: "object",
  properties: {
    items: {
      type: "array",
      items: {
        type: "object",
        properties: {
          id: { type: "string", description: "Kataloqda hədiyyənin ID-si." },
          score: {
            type: "number",
            description: "Profilə uyğunluq balı (0..1)."
          },
          reason: {
            type: "string",
            description:
              "Hədiyyənin niyə uyğun olduğunu qısa izah et (backend-də generasiya oluna bilər)."
          }
        },
        required: ["id", "score"]
      },
      description: "Uyğunluq balları ilə tövsiyə olunan hədiyyələr siyahısı."
    },
    meta: {
      type: "object",
      properties: {
        totalCandidates: {
          type: "integer",
          description: "Kataloqda ümumilikdə neçə namizəd tapıldı."
        },
        returned: {
          type: "integer",
          description: "Bu çağırış neçə hədiyyə qaytardı."
        },
        advice: {
          type: "string",
          description:
            "Ümumi tövsiyə: məsələn, hansı tip hədiyyələrdən başlamaq məntiqlidir."
        }
      }
    }
  },
  required: ["items"]
};

Və bu sxemi implementasiyanın içində istifadə edirik:

server.registerTool(
  "recommend_gifts",
  {
    title: "Hədiyyə tövsiyələri",
    description:
      "Segmentlərə və büdcəyə görə 3–7 hədiyyə seçmək lazım olduqda istifadə et. Hədiyyə id-lərini və uyğunluq ballarını qaytarır; ətraflı kartları get_gift vasitəsilə al.",
    inputSchema: /* yuxarıdakı kimidir */,
    // Bəzən formal olaraq outputSchema göstərilmir, amma sənədləşmə üçün faydalıdır:
    // outputSchema: recommendGiftsOutputSchema
  },
  async ({ input }) => {
    const recommendations = await recommendFromCatalog(input); // bizim biznes-məntiq

    return {
      content: [
        {
          type: "text",
          text: `Uyğun ${recommendations.items.length} ideya tapdım. İndi ən yaxşılarını göstərəcəyəm.`
        }
      ],
      structuredContent: {
        items: recommendations.items,
        meta: {
          totalCandidates: recommendations.meta.totalCandidates,
          returned: recommendations.items.length,
          advice: recommendations.meta.advice
        }
      }
    };
  }
);

Biz iki işi görürük: modelə istifadəçi üçün minimal mətn veririk və eyni zamanda semantik JSON qoyuruq ki, onun əsasında model dialoqu və follow‑up-u qura bilsin.

Bu arada get_gift id üzrə artıq tam kartları (ad, media, SKU və s.) çəkəcək, GiftGenius vidjeti isə onları hədiyyə kartları kimi render edəcək.

5. Discovery üçün alətlərin adlandırılması və təsvirləri əsasdır

İndi ən maraqlısı: alətlərin adları və təsvirləri modelin onları çağırıb-çağırmamasına necə təsir edir.

Sənədlər və metadata üzrə best practice belə məsləhət görür:

• action‑oriented adlardan istifadə edin: profile_to_segments, recommend_gifts, get_gift, similar_gifts, yoxsa tool1, search, do_stuff deyil;
• təsviri “Use this when… / Bu alətdən istifadə et, əgər…” üslubunda başlayın, tetik ssenariləri və məhdudiyyətləri (“bunun üçün istifadə etmə…”) təsvir edin.

Bu, birbaşa sizin golden prompt set ilə bağlıdır. Təsvir formulyasiyaları real istifadəçi sorğuları ilə kəsişməlidir. Əgər təsvirinizdə “Alıcının maraqları və büdcəsinə görə hədiyyə seçmək lazım olduqda istifadə et” yazılıbsa və golden prompt-da “gamer dost üçün $50-a qədər hədiyyə seç” var idisə, modelin sorğunu alətlə uyğunlaşdırması xeyli asanlaşır.

Yaxşı alət təsvirinə nümunə

GiftGenius-un əlavə alətini — konkret hədiyyə əsasında oxşar ideyalar təklif edən similar_gifts-i nəzərdən keçirək:

server.registerTool(
  "similar_gifts",
  {
    title: "Oxşar hədiyyələr",
    description:
      "İstifadəçi konkret bir hədiyyə seçdikdə və ona bənzər bir neçə variant görmək istədikdə bu alətdən istifadə et. İlk seçim üçün sıfırdan istifadə etmə — bunun üçün recommend_gifts var.",
    inputSchema: {
      type: "object",
      properties: {
        giftId: {
          type: "string",
          description:
            "Oxşar variantların tapılacağı əvvəlki seçimin hədiyyə identifikatoru."
        },
        limit: {
          type: "integer",
          description:
            "Neçə oxşar hədiyyə qaytarılsın (standart 3–5).",
          minimum: 1,
          default: 5
        }
      },
      required: ["giftId"]
    }
  },
  async () => {
    /* ... */
  }
);

Vacib məqamlar:

• Aləti nə vaxt istifadə etmək, nə vaxt etməmək lazım olduğunu açıq deyirik.
• Təsvir real sorğularda tez-tez rast gəlinəcək “oxşar variantlar”, “konkret hədiyyə seçdi” kimi sözləri ehtiva edir.
• recommend_gifts sahəsi ilə kəsişmədən qaçırıq — bu, seçim zamanı alətlər arasında rəqabəti azaldır.

Yaman alət təsviri nümunəsi

description: "Hədiyyələrlə iş."

Model bu təsvirindən demək olar ki, heç nə anlamır. Belə alət yalnız GPT artıq “təsadüfə” ümid edəndə işə yaraya bilər.

6. Annotasiyalar və hints: əməliyyatın ciddiliyini modelə necə göstərməli

Alət təkcə ad və sxem deyil, həm də ChatGPT-yə əməliyyatın nə dərəcədə təhlükəli/əhəmiyyətli olduğunu və istifadəçidən təsdiq alınıb-alınmamasını bildirən annotasiyalardır. Apps SDK spesifikasiyasında bunun üçün readOnlyHint, destructiveHint, openWorldHint və digər müxtəlif hints mövcuddur.

• readOnlyHint: true alətin yalnız oxuduğunu və vəziyyəti dəyişmədiyini bildirir. Bu halda assistent artıq təsdiqləri keçə və onu daha sərbəst çağıra bilər.
• destructiveHint: true alətin nəyisə silə və ya geri dönməz şəkildə dəyişə biləcəyini siqnal verir, buna görə istifadəçiyə “Əminsiniz?” sualı göstərilməlidir.
• openWorldHint: true əməliyyatın xarici dünyaya toxunduğunu göstərir (sosial şəbəkələrdə postlama, hesabdan kənar yazı yaratma və s.) və bu barədə xəbərdar etmək də vacibdir.

Minimum səviyyə — təsdiqsiz

Əgər sizdə public readonly tools varsa, onları readOnlyHint: true kimi işarələmək məntiqlidir. Nümunə:

"annotations": {
  "readOnlyHint": true,
  "destructiveHint": false,
  "openWorldHint": false
}

Belə alətlər GPT tərəfindən əlavə dialoq təsdiqləri olmadan çağırıla bilər.

Bir təsdiq

Serverdə nəyisə dəyişən tools varsa, onları readOnlyHint: false kimi işarələmək məntiqlidir:

"annotations": {
  "readOnlyHint": false,
  "destructiveHint": false,
  "openWorldHint": false
}

Model belə aləti görəndə çox güman ki, istifadəçidən bir dəfə təsdiq istəyəcək (adətən bu, ChatGPT UI-da modal dialoq pəncərəsidir).

Təhlükəli əməliyyat

Serverdə nəyisə silən alətiniz varsa, onu destructiveHint: true kimi işarələyin:

"annotations": {
  "readOnlyHint": false,
  "destructiveHint": true,
  "openWorldHint": false
}

Model bu aləti çox ehtiyatla çağıracaq və iki dəfə dəqiqləşdirəcək:

• əvvəlcə mətndə istifadəçidən təsdiq istəyəcək,
• sonra platforma standart dialoq pəncərəsini göstərəcək.

Bu modul daxilində GiftGenius üçün hələ commerce alətləri yazmırıq, amma gələcək create_gift_order-in necə görünəcəyini cızmaq olar:

server.registerTool(
  "create_gift_order",
  {
    title: "Hədiyyə sifarişinin yaradılması",
    description:
      "Yalnız istifadəçinin seçilmiş hədiyyəni almağa açıq razılığından sonra istifadə et. Sistemdə sifariş yaradır və statusu qaytarır.",
    inputSchema: {
      type: "object",
      properties: {
        giftId: {
          type: "string",
          description: "İstifadəçinin seçdiyi hədiyyənin ID-si."
        },
        deliveryEmail: {
          type: "string",
          description: "Rəqəmsal hədiyyənin göndəriləcəyi email."
        }
      },
      required: ["giftId", "deliveryEmail"]
    },
    annotations: {
      destructiveHint: true,
      openWorldHint: true
    }
  },
  async () => {
    /* ... */
  }
);

Annotasiyalar serverdəki səlahiyyət yoxlamalarınızı əvəz etmir, sadəcə ChatGPT-yə UX qurmağa kömək edir: təsdiq istəmək, xəbərdarlıq göstərmək və belə alətləri “səssizcə” icra etməmək.

7. App metadatası və discovery-nin iki səviyyəsi

Alətlər hekayənin yarısıdır. İkinci yarısı — istifadəçi ümumiyyətlə App-ınızı necə tapır və işə salır.

ChatGPT ekosistemində discovery-nin iki əsas səviyyəsi var.

Birincisi — in‑conversation discovery. İstifadəçi çatda nəsə yazanda (App-ı açıq şəkildə qeyd etməsə belə), model baxır:

• mesajın mətni və dialoq tarixçəsinə;
• mövcud tətbiqlərin və onların alətlərinin təsvirlərinə;
• brend-mentionlara, mövzuya və açar frazalara.

Bunun əsasında o qərar verir ki, hansısa App təklif etmək lazımdırmı və əgər bəli isə hansını və hansı ssenari ilə. Burada alətlərin və App-ın öz təsvirləri xüsusilə önəmlidir. Əgər onlarda “hədiyyə seçimi”, “hədiyyə ideyası”, “hədiyyə büdcəsi” kimi “tetiklər” varsa, modelin App-ınızı seçmə şansı kəskin artır.

İkinci səviyyə — qlobal discovery: kataloq və launcher. Burada artıq rolu insan oynayır: o, App-ı ada, ikona, qısa təsvirə və teqlərə baxaraq seçir. Burada tətbiqinizin nə etdiyini, kimə görə olduğunu və əsas dəyər təklifinin nə olduğunu düzgün və aydın izah etmək vacibdir.

Kiçik bir cədvəldə toplaya bilərik:

GiftGenius üçün məsələn belə formalaşdırmaq olar:

• Ad: GiftGenius — 60 saniyədə hədiyyə seçimi.
• Qısa təsvir: Alıcının profilini toplayır və 5–7 hədiyyə ideyası təklif edir, alış imkanı birbaşa ChatGPT daxilindədir.
• In‑conversation üçün təsvir: İstifadəçi hədiyyə seçməyə kömək istəyəndə, nə hədiyyə alacağını bilməyəndə, büdcəni, alıcının maraqlarını və ya səbəbi dedikdə bu tətbiqdən istifadə et.

Bu formulyasiyaları system‑prompt və recommend_gifts alətinin təsvirində yazdıqlarınızla sinxronlaşdırmaq çox arzuolunandır. Onda model ayrı-ayrı ziddiyyətli mətnlər deyil, bütöv mənzərə görür.

8. Marşrutlaşdırma ChatGPT-nin “beynində” necə işləyir

Hamısını bir yerə yığaq və tipik sorğu yoluna baxaq — MCP protokoluna dərinə girmədən, bu, növbəti modullarda olacaq.

Qoy istifadəçi belə yazsın:

“Qardaşa hədiyyə fikirləşməyə kömək et, futbolu və stolüstü oyunları çox sevir, büdcə $50-a qədər.”

Təxmini sadələşdirilmiş alqoritm:

1. Model mesajı və tarixçəni təhlil edir. “hədiyyə”, “qardaş”, “futbol”, “stolüstü”, “büdcə 50” sözlərini görür.
2. Bunu mövcud App-ların və onların alətlərinin təsvirləri ilə müqayisə edir. GiftGenius üçün təsvirlər “maraqlar və büdcə üzrə hədiyyə seçimi”ni açıq ehtiva etdiyi üçün App-ın əlaqədar olma ehtimalı yüksəkdir.
3. Əgər App bu sessiyada hələ aktiv deyilsə, model elan replikası formalaşdırır: “Sizin parametrlərinizə görə hədiyyə seçməyə kömək edən GiftGenius tətbiqini aça bilərəm. Açaq?” — bunu əvvəlcədən UX təlimatlarında yazmışıq.
4. İstifadəçi razılıq verdikdən sonra model App daxilində recommend_gifts alətini seçir, çünki məhz onun təsviri cari niyyətə ən yaxşı uyğun gəlir. Burada həm ad, həm description, həm də inputSchema-nın strukturu siqnal kimi işləyir.
5. Model alətin arqumentlərini sorğu əsasında doldurur: əvvəl (lazımdırsa) “qardaş, futbol və stolüstü oyunları sevir” mətnindən ["football_fan", "board_games"] segmentlərini almaq üçün profile_to_segments-i çağırır, sonra isə recommend_gifts-i segments, budget: {min: 0, max: 50, currency: "USD"}, locale, occasion: "birthday" ilə çağırır.
6. MCP serveri aləti icra edir, items və meta ilə structured output formalaşdırır və geri qaytarır.
7. Model sizin outputSchema-da təsvir etdiyiniz JSON-u oxuyur və cavabı qurur: nə tapdığını, niyə məhz bu hədiyyələri seçdiyini izah edir və follow‑up təklif edir (“kateqoriyaya görə daraldaq?”, “bu hədiyyəyə oxşarları göstərim?” və ya “bu hədiyyənin alışını rəsmiləşdirim?”).

Bu prosesin sadə blok‑sxemi belədir:

flowchart TD
  A[Istifadəçi: hədiyyə barədə sorğu] --> B[ChatGPT konteksti təhlil edir]
  B --> C[App və tools metadataları ilə müqayisə]
  C -->|əlaqədardır| D[GiftGenius anonsu]
  D -->|istifadəçi razıdır| E["recommend_gifts çağırışı (+ profile_to_segments)"]
  E --> F[GiftGenius MCP serveri]
  F --> G[items/meta ilə JSON nəticə]
  G --> H[Model cavabı və follow-up-u formalaşdırır]

Siz alətləri və use‑case-ləri nə qədər yaxşı təsvir etsəniz, burada bir o qədər az təsadüf, bir o qədər stabil marşrutlaşdırma olacaq.

Insight: Tool Call SEO

Apps ekosistemində tezliklə təkcə kataloqda insanların diqqəti uğrunda yox, həm də modelin öz diqqəti uğrunda rəqabət olacaq. Eyni istifadəçi sorğusuna ChatGPT bir neçə fərqli tətbiqi çağıra bilər və seçim artıq kimin təqdimat dizaynının yaxşı olduğuna görə deyil, modelin beynindəki “axtarış nəticələri”nə görə baş verəcək. Bu görünməyən lay getdikcə SEO-ya bənzəyir, sadəcə səhifələr əvəzinə sizin tools və MCP serverləriniz var.

Model mahiyyətcə namizədləri rütbləyir: əvvəl App səviyyəsində, sonra isə ayrı alətlər səviyyəsində. O, ada, descriptions‑a, sxemlərə, annotasiyalara baxır və onları sorğunun formulyasiyaları ilə tutuşdurur. Əgər recommend_gifts təsvirində “alıcı maraqları və büdcəsinə görə hədiyyə seçimi” varsa və sorğuda “gamer dosta $50-a hədiyyə seç” səslənirsə, “hədiyyələrlə iş” təsviri olan abstrakt search-dən fərqli olaraq bu alətin “topa düşmək” şansı daha yüksəkdir.

Buradan praktik Tool Call SEO ideyası doğur: adlara, descriptions‑a, enum dəyərlərinə və metadatalara açar sözlər və snippətlər kimi yanaşın. Siz təkcə developer-lər üçün müqavilə təsvir etmirsiniz — onu golden prompt set-dən gələn real sorğu trafikinə optimallaşdırırsınız. Çox ümumi formulyasiyalar, bir neçə alətin kəsişən sahələri, nişəsi dəqiq olmayan God‑alətlər — bunlar App-ınızın model beynindəki “CTR”-ini aşağı salır.

9. Kiçik praktik tapşırıq

Bunu fikrən (və ya repozitoriyinizdə) yerinə yetirməyə çalışın.

Əvvəlcə GiftGenius-un əsas ssenarilərindən birini seçin — məsələn, “Məhdud büdcə ilə iş yoldaşına hədiyyə seçin”.

Bunun üçün formalaşdırın:

1. Bu ssenari üçün hansı ayrı alət lazımdır: bu, təmiz recommend_gifts-dir, yoxsa B2B‑case üçün əlavə ixtisaslaşmış alət lazımdır, ya da deyək ki, recommend_gifts-dən sonra variasiyalar üçün similar_gifts kifayətdir?
2. recommend_gifts-in giriş sxemində hansı sahələr həqiqətən vacibdir. Hansı sahələri modelin təxmin etməsinə məcbur etmədən ayrıca (follow‑up ilə) istifadəçidən soruşmaq olar.
3. Modelin seçimi dürüst izah edə bilməsi və növbəti addımları təklif etməsi (məsələn, B2B rejiminə keçmək, yalnız rəqəmsal hədiyyələri göstərmək, qiymət intervalına görə daraltmaq) üçün outputSchema necə görünməlidir.

Sonra isə keçən mühazirədəki golden prompt set-inizə baxın və yoxlayın:

• hər etalon sorğu üçün aydın bir alət varmı (recommend_gifts, get_gift, similar_gifts və s.);
• elə olmur ki, iki alət eyni sorğuya eyni dərəcədə “uyğundur” (overlapping tools);
• modelin daha az çaşması üçün təsvirləri gücləndirmək və ya hansısa aləti yenidən adlandırmaq lazımdırmı.

Bu, məhz hər ciddi prompt, sxem və ya məntiq dəyişikliyindən əvvəl təkrarlayacağınız prosesdir — mahiyyətcə discovery keyfiyyətinin mini‑eval-ı.

Yuxarıdakıları qısa yoxlama siyahısına toplasaq, bu mərhələdə etməli olduqlarınız:

• ssenariləri 2–4 mənalı alətə ədalətlə bölmək;
• inputSchema/outputSchema-nı nümunələr və enum-larla səliqə ilə təsvir etmək;
• adları, descriptions və annotasiyaları qaydaya salmaq;
• bunu system‑prompt və App-ın metadatası ilə sinxronlaşdırmaq.

Növbəti modullarda artıq bütün bunların MCP üzərindən necə işlədiyini və discovery/marşrutlaşdırmanın qəribə davranışını necə diaqnostika etməyi görəcəyik.

10. Tools və metadata layihələndirməsində tipik səhvlər

Xəta №1: “Hər şeyi system‑prompt-da təsvir etdik, alətlər nəsə başa düşər”.
Əgər App-ın rolunu, məsuliyyət sərhədlərini və UX davranışını əla yazmısınızsa, amma alətləri tool1, search, do_stuff kimi adlarla və təsvirsiz sxemlərlə buraxmısınızsa, model gözəl mətninizi real çağırışlarla əlaqələndirə bilməyəcək. ChatGPT üçün alətlər əsas interfeysdir; düzgün metadata olmadan heç bir system‑prompt xilas etməyəcək.

Xəta №2: Hər şeyi edən God Tool.
mode parametri ilə bir funksiyanı “optimallaşdırma” istəyi anlaşılandır, amma nəhəng JSON sxemlərinə, təsvirlərdə qarışıqlığa və marşrutlaşdırmanın pisləşməsinə gətirib çıxarır. Model hansı rejimi istifadə etməli olduğunu təxmin etməyə başlayır, siz isə serverdə nəhəng switch saxlayırsınız. Konkret ssenari addımları üçün bir neçə dəqiq alət, “hər şeyi et” alətindən daha yaxşıdır.

Xəta №3: “Birdən lazım olar” deyə doldurulmuş giriş sxemi.
Tərtibatçılar tez-tez inputSchema vasitəsilə hər vaxt lazım ola biləcək bütün parametrləri, üstəlik bir-iki daxili sahəni də dərhal ötürməyə çalışırlar. Nəticədə model heç cür bilməyəcəyi şeyləri (məsələn, tenantId) təxmin etməyə çalışır, siz isə qəribə dəyərlərə təəccüblənirsiniz. Input Schema yalnız modelin dialoqdan çıxara biləcəyi və ya sualla dəqiqləşdirə biləcəyi şeyləri ehtiva etməlidir. Daxili detallarınızı serverdə əlavə edin.

Xəta №4: Meta məlumat olmadan “lal” output məlumatları.
Alətdən sadəcə obyekt massivi qaytarmaq cazibədardır. Amma beləliklə, modelə bu nəticələrin nəyə görə göründüyünü anlama imkanı vermirsiniz. score, reason, searchCriteria, totalCandidates kimi sahələr olmadan dürüst izah və follow‑up qurmaq çətindir. Axtarış meyarları və məsləhətlərlə kiçik meta qabığı əlavə etmək çox vaxt cavab keyfiyyətini radikal yaxşılaşdırır.

Xəta №5: Vaqonka tipli təsvirlər: “Hədiyyələrlə iş”, “Kurs axtarışı”, “Məlumat emalı”.
Belə təsvirlər modelə nə tetik, nə də məhdudiyyət verir. O, aləti nə vaxt çağırmalı olduğunu və hansı sahədə tətbiq olunduğunu bilmir. Yaxşı təsvir “Bu alətdən istifadə et, əgər…” ilə başlayır və konkret ssenarilər və “Bunun üçün istifadə etmə…” tipli qadağaları ehtiva edir. İdeal halda bu formulyasiyalar golden prompt set-dəki qızıl sorğularla kəsişir.

Xəta №6: Annotasiyaları görməzdən gəlmək və read‑only ilə dəyişdirən əməliyyatları qarışdırmaq.
Yalnız məlumat oxuyan alətləri (readOnlyHint) və əməliyyat edənləri (destructiveHint, openWorldHint) işarələməsəniz, model düzgün təsdiq UX-i qura bilmir. Nəticədə ya hər addımda artıq “Əminsiniz?” sualları, ya da əksinə, istifadəçinin razılığı olmadan səssiz alışlar və dəyişikliklər olur. Annotasiyalar əməliyyatın önəmini modelə bildirməyin ucuz və effektiv yoludur.

Xəta №7: Kataloq üçün App metadatası və in‑conversation üçün metadata ayrı-aləm yaşaması.
Bəzən olur ki, kataloqdakı qısa təsviri marketoloq yazıb (“Həyatınızı dəyişən inqilabi AI‑assistent”), tools təsvirlərini və system‑prompt-u isə tərtibatçı (“büdcəyə görə hədiyyə seçimi”). Nəticədə kataloqda ümumiyyətlə App-ın nədən ibarət olduğu anlaşılmır, model isə çatda “bu nə servisdır?” tipli sorğuları App-ın real imkanları ilə uyğunlaşdıra bilmir. Metadatanı tək spesifikasiya kimi yazın, iki müstəqil marketinq mətnləri kimi yox.