أنماط تعريف الأدوات

مساعدو الذكاء الاصطناعي الحديثون بقدر قوة أدواتهم فقط. فهم كيف تحدد الأنظمة الإنتاجية الأدوات في مطالباتها النظامية يكشف أنماطاً لبناء أنظمة أدوات قوية وآمنة.

هيكل تعريف الأدوات

الأدوات الإنتاجية تتبع أنماطاً متسقة:

{
  "name": "tool_name",
  "description": "Clear explanation of what this tool does",
  "parameters": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "What this parameter controls"
      }
    },
    "required": ["param1"]
  }
}

تعريفات أدوات Claude Code

من المطالبة النظامية لـ Claude Code (يناير 2026):

{
  "name": "Read",
  "description": "Reads a file from the local filesystem. You can access any file directly by using this tool. Assume this tool is able to read all files on the machine.",
  "parameters": {
    "properties": {
      "file_path": {
        "description": "The absolute path to the file to read",
        "type": "string"
      },
      "offset": {
        "description": "Line number to start reading from",
        "type": "number"
      },
      "limit": {
        "description": "Number of lines to read",
        "type": "number"
      }
    },
    "required": ["file_path"]
  }
}

الأنماط الرئيسية:

• وصف واضح للقدرة
• المعلمات المطلوبة مقابل الاختيارية
• مواصفات الأنواع
• سياق الاستخدام

فئات الأدوات

الأنظمة الإنتاجية تنظم الأدوات حسب الوظيفة:

1. عمليات الملفات

File Tools:
- Read: Access file contents
- Write: Create new files
- Edit: Modify existing files
- Glob: Pattern-based file search
- Grep: Content search

Usage rules:
- Use Read before Edit (always)
- Prefer Edit over Write for existing files
- Use Glob for file discovery
- Use Grep for content search

2. أدوات التنفيذ

Execution Tools:
- Bash: Run shell commands
- Task: Spawn sub-agents
- WebFetch: Retrieve web content
- WebSearch: Search the internet

Constraints:
- Bash has timeout limits
- Task agents have scoped permissions
- Web tools respect rate limits

3. أدوات الاتصال

Communication Tools:
- AskUserQuestion: Get user input
- TodoWrite: Track task progress
- ExitPlanMode: Complete planning phase

Guidelines:
- Minimize user interruptions
- Use TodoWrite for complex tasks
- Clear question formatting

أفضل ممارسات وصف الأدوات

من المطالبات النظامية الحقيقية:

كن محدداً حول القدرات

سيء:

"description": "Searches files"

جيد:

"description": "Fast file pattern matching tool that works with any codebase size. Supports glob patterns like '**/*.js' or 'src/**/*.ts'. Returns matching file paths sorted by modification time."

تضمين إرشادات الاستخدام

"description": "Executes a bash command with optional timeout.

Usage notes:
- Commands timeout after 120000ms by default
- Output truncated after 30000 characters
- Use for git, npm, docker operations
- NOT for file reading (use Read tool instead)"

تقديم أمثلة

"description": "Edits files using exact string replacement.

Examples:
- Replace function name: old_string='function foo', new_string='function bar'
- Fix import: old_string='import x', new_string='import { x }'

The old_string must be unique in the file."

تصميم المعلمات

المطلوب مقابل الاختياري

{
  "properties": {
    "path": {
      "description": "Required: Directory to search",
      "type": "string"
    },
    "pattern": {
      "description": "Required: Glob pattern to match",
      "type": "string"
    },
    "depth": {
      "description": "Optional: Max directory depth (default: unlimited)",
      "type": "number"
    }
  },
  "required": ["path", "pattern"]
}

قيود الأنواع

{
  "timeout": {
    "type": "number",
    "minimum": 0,
    "maximum": 600000,
    "description": "Timeout in milliseconds (max 10 minutes)"
  },
  "output_mode": {
    "type": "string",
    "enum": ["content", "files_with_matches", "count"],
    "description": "What to return from search"
  }
}

أنماط اكتشاف الأدوات

كيف يعرف الوكلاء أي أداة يستخدمون:

الاختيار القائم على الفئة

Tool Selection Guidelines:
- File operations → Read, Write, Edit, Glob
- Code search → Grep, Glob
- System commands → Bash
- Research → WebSearch, WebFetch
- Complex tasks → Task (spawn agent)

NEVER use Bash for:
- File reading (use Read)
- File editing (use Edit)
- File search (use Glob/Grep)

التوجيه القائم على السياق

Context-Aware Tool Selection:
If searching for files by name:
  → Use Glob
If searching for content in files:
  → Use Grep
If exploring unknown codebase:
  → Use Task with Explore agent
If running build/test:
  → Use Bash

تركيب الأدوات

دمج الأدوات للعمليات المعقدة:

Composition Pattern: Code Modification
1. Glob to find relevant files
2. Read to understand current code
3. Edit to make changes
4. Bash to run tests
5. Read to verify changes

Example flow:
- Glob("**/*.ts") → Find TypeScript files
- Grep("deprecated") → Find deprecated usage
- Read(file) → Understand context
- Edit(file, old, new) → Update code
- Bash("npm test") → Verify changes

صلاحيات الأدوات

الأنظمة الإنتاجية تتحكم في وصول الأدوات:

Permission Levels:
ALLOWED (no approval needed):
- Read, Glob, Grep
- WebSearch, WebFetch
- Safe Bash commands (ls, git status)

REQUIRES_APPROVAL:
- Write, Edit
- Bash with side effects
- Task spawning

NEVER_ALLOWED:
- Destructive operations
- Credential access
- Network egress to unknown hosts

وضع Yolo في Cursor

Cursor يسمح بتجاوز الموافقات:

Yolo Mode Configuration:
When enabled:
- File writes proceed without confirmation
- Bash commands execute immediately
- Agent has higher autonomy

Risk mitigation:
- Git provides rollback
- Sandboxed environment
- User can interrupt

الأنماط المضادة

ما يجب تجنبه في تعريفات الأدوات:

Anti-Pattern 1: Vague descriptions
❌ "description": "Does stuff with files"
✓ "description": "Creates a new file at the specified path with given content"

Anti-Pattern 2: Missing constraints
❌ No max length, no timeout
✓ "maximum": 10000, "timeout": 60000

Anti-Pattern 3: Overlapping tools
❌ Multiple tools that do similar things
✓ Clear separation of concerns

Anti-Pattern 4: Hidden side effects
❌ Tool that reads AND modifies
✓ Separate Read and Edit tools

رؤية رئيسية: تعريفات الأدوات المصممة جيداً هي أساس مساعدي الذكاء الاصطناعي القادرين. الأوصاف الواضحة، القيود المناسبة، والتصنيف المنطقي تمكن الوكلاء من اختيار الأداة الصحيحة لكل مهمة مع الحفاظ على السلامة.

بعد ذلك، سنستكشف صيغة استدعاء الوظائف عبر منصات الذكاء الاصطناعي المختلفة. :::