تعريف الـ Tool Schema

فكّر فيه كإعلان وظيفة للأداة: اسمها، شغلانتها، والحاجات اللي لازم تجيبها معاك. كل ما تكتبه أوضح، كل ما الموديل يستخدمها أحسن.

زي اللافتة اللي على زراير ماكينة السناكس: الموديل بيقرأ الوصف اللي مكتوب بس عشان يقرر يدوس على أنهي زرار — لو الوصف غلط، هيطلب الحاجة الغلط.

أداة send_email فيها: description «يبعت إيميل لعميل»، وparameters: to (نص، إيميل)، subject (نص)، body (نص) — كلهم required. الموديل بيملاهم من كلام المستخدم.

الـ schema بيتكتب بصيغة JSON Schema: اسم (name)، وصف (description)، وparameters فيها نوع كل مدخل، والقيم المسموحة (enum لو فيه)، وأنهي حقول required. التعريفات دي بتتبعت مع كل request جوه الـ context، فالموديل «بيقراها» كل مرة زي أي prompt — يعني بتاكل tokens، والوصف الكويس هو أهم prompt engineering في الأداة كلها. الموديل بعدين بيولّد مدخلات على شكل الـ schema — بس ده مش ضمان: لازم كودك يتحقّق (validate) قبل التنفيذ.

مثال schema لأداة طقس — لاحظ الوصف المحدّد والـ enum:

{
  "name": "get_weather",
  "description": "يجيب حالة الطقس الحالية لمدينة. استخدمها بس لما المستخدم يسأل عن طقس دلوقتي، مش توقعات.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "اسم المدينة بالإنجليزي، مثال: Cairo" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["city"]
  }
}

🧪 جرّب بنفسك: اكتب JSON schema كامل لأداة حاسبة calculate — فكّر: العملية (جمع/طرح/ضرب/قسمة) تبقى enum ولا نص حر؟ الأرقام required؟ والوصف يقول إيه عشان الموديل يستخدمها في الحساب بدل ما يخمّن بنفسه؟ بعدين اختبر: هل حد يقدر يسيء فهم الـ schema بتاعك؟

أشهر الأخطاء: (1) وصف مبهم زي «بتجيب داتا» — الموديل مش هيعرف إمتى يستخدمها. (2) كل الحقول optional فالموديل بيسيبها فاضية. (3) مفيش enum للقيم المحدودة فالموديل بيخترع قيم. (4) اسمين متشابهين لأداتين مختلفتين — الموديل بيلخبط بينهم. (5) الاعتماد على الـ schema لوحده كتحقّق — الـ schema بيوجّه الموديل، بس الـ validation الحقيقي في كودك.

اكتب schema مفصّل لأي أداة الموديل هيشوفها: وصف بيقول إمتى تُستخدم (وإمتى لأ)، أنواع صارمة، وenum لأي قيمة محدودة.

متحطش في الـ schema تفاصيل تنفيذ داخلية (أسماء جداول، endpoints) — دي مش بتساعد الموديل، وبتاكل tokens، وبتكشف بنيتك الداخلية من غير داعي.