هندسة الأدوات Tool Engineering

🔧 تشريح الأداة الجيدة

**كل أداة تحتاج:** 1️⃣ **اسم واضح:** يصف ما تفعله ❌ `process` ✅ `search_product_database` 2️⃣ **وصف دقيق:** متى تُستخدم ❌ "للبحث" ✅ "ابحث في قاعدة بيانات المنتجات بالاسم أو الفئة أو السعر" 3️⃣ **معاملات محددة:** ما المدخلات المطلوبة - اسم المعامل واضح - النوع محدد (نص، رقم، قائمة) - أمثلة للقيم المتوقعة 4️⃣ **مخرج متوقع:** ماذا تُرجع - التنسيق (JSON، نص، قائمة) - حالات الخطأ

📝 نموذج تعريف أداة (Tool Schema)

```json { "name": "search_orders", "description": "ابحث عن طلبات العميل. استخدمها عندما يسأل العميل عن طلب أو شحنة.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "رقم الطلب (مثال: ORD-12345)" }, "customer_email": { "type": "string", "description": "إيميل العميل للبحث بالحساب" }, "status": { "type": "string", "enum": ["pending", "shipped", "delivered"], "description": "فلترة حسب حالة الطلب" } }, "required": [] } } ```

⚠️ أخطاء شائعة في تصميم الأدوات

**❌ أسماء غامضة:** `do_thing` → ✅ `send_email_notification` **❌ وصف ناقص:** "للبحث" → ✅ "ابحث في المنتجات بالاسم. أرجع أول 10 نتائج." **❌ معاملات بدون أنواع:** `date` → ✅ `date (string, format: YYYY-MM-DD)` **❌ مسارات نسبية:** `./file.txt` → ✅ `/absolute/path/file.txt` (اكتشاف Anthropic من SWE-bench) **❌ أدوات متشابهة:** إذا كان لديك `search_v1` و `search_v2` → الوكيل يرتبك!

💡 نصيحة Poka-yoke للأدوات

**Poka-yoke (防呆):** مصطلح ياباني = "تجنب الخطأ" **كيف تطبقها على الأدوات:** 1️⃣ **افرض التنسيق الصحيح:** • بدل قبول تاريخ بأي صيغة → افرض ISO format • بدل نص حر → قائمة خيارات (enum) 2️⃣ **تحقق قبل التنفيذ:** • هل المعاملات المطلوبة موجودة؟ • هل القيم منطقية؟ 3️⃣ **أرجع رسائل خطأ مفيدة:** ❌ "Error" ✅ "رقم الطلب غير صالح. الصيغة المتوقعة: ORD-XXXXX" 4️⃣ **وفر أمثلة في الوصف:** "مثال: search_orders(order_id='ORD-12345')"

🏆 مكافأة