Orqestria Download
← Zurück zu Entwickler interner Systeme

Skill · Version 1.0.0

Werkzeugaufrufverträge

Definiert eindeutige KI-Werkzeuge mit begrenzten Eingaben, geprüfter Ausführung und kontextschonenden Ergebnissen.

tool-calling-contracts

Teammitglieder mit diesem Skill

Entdecke, wie der Skill hilft

Wann ist der Skill hilfreich?

Nutze dies bei falschen Werkzeugaktionen oder übergroßen Ergebnissen.

Wobei hilft er dir?

  • Verwendet klare Fachaktionen und präzise Schemabedingungen.
  • Trennt Argument-, Berechtigungs- und Geschäftsregelprüfung.
  • Liefert strukturierte Fehler und begrenzte Ausgaben für gezielte Wiederherstellung.

Das könntest du fragen

Gestalte Projektsuche mit begrenzten Treffern und ausdrücklichem Fehler für unzugängliche Projekte. Fordere zu viele Treffer mit fremder Projektkennung an. Liefere begrenzte typisierte Antworten; die Ablehnung verrät keine unzugänglichen Projektdetails.

Ausführliche Dokumentation

Hier findest du die ursprüngliche Anleitung, Beispiele und Prüfschritte des Skills in ihrer Originalsprache.

Details…Weniger anzeigen

Tool Calling & Execution Contracts

Tools are the API boundary between a probabilistic model and deterministic application state. Design every tool so its contract is unmistakable to the model, strictly validated at runtime, bounded in output size, and safe under retries.

Designing High-Signal Tool Schemas

  1. Action-oriented, unambiguous names: Use snake_case verbs scoped by domain (orders_get_by_id, repo_search_code, calendar_propose_slot). Avoid overloaded swiss-army tools with modal action: "create" | "update" | "delete" | "search" parameters when separate tools have distinct schemas and permission levels.
  2. Tight JSON Schema constraints:
    • Set "additionalProperties": false on object schemas so hallucinated fields fail fast.
    • Prefer enum, bounded numeric ranges (minimum, maximum), and pattern-constrained strings over free-form string.
    • Write parameter description fields that state units, format, and preconditions (e.g., "ISO-8601 UTC timestamp (YYYY-MM-DDTHH:mm:ssZ). Must be >= start_time.").
  3. Behavioral annotations: Attach explicit metadata to every tool registration:
    • readOnlyHint: true if the tool never mutates state.
    • destructiveHint: true if the tool deletes or overwrites data irreversibly.
    • idempotentHint: true if repeated calls with identical arguments have no additional effect.
    • timeoutMs and maxOutputBytes: Explicit execution bounds enforced by the dispatcher.

Three-Layer Validation & Error Recovery

Distinguish protocol errors from model-correctable tool failures:

Failure Class Example How the Dispatcher Must Respond
Schema / Argument Validation Missing required field, invalid enum value, malformed date Do not throw an unhandled exception. Return a tool result with isError: true listing the exact JSON path and expected constraint so the model can self-correct on the next turn.
Domain / Precondition Error Order #4821 not found, File modified since last read, Insufficient permissions Return isError: true with a concise, structured recovery hint (e.g., "File changed on disk; call read_file before editing").
Transient Infrastructure Failure 429, 503, connection reset on an idempotent backend Retry inside the tool adapter with exponential backoff + jitter before surfacing a failure to the model.
Fatal Runtime / Bug Null pointer in tool implementation, revoked service credentials Log full stack trace to telemetry, redact internals, return isError: true with "Tool temporarily unavailable (ref: <trace_id>); do not retry this tool", and trip the tool circuit breaker.

Output Shaping & Context Protection

Never dump raw database rows, full HTML pages, or multi-megabyte command outputs into tool_result:

  • Project and paginate: Return only the fields required for the task, plus pagination cursors (next_cursor, total_matching, truncated: true).
  • Deterministic truncation: If a tool output exceeds maxOutputBytes (e.g., 32 KB), store the full payload as an addressable artifact/resource and return a structured summary (head, tail, byte/line counts, and instructions on how to query specific ranges).
  • Idempotency & dry-run support: For mutating tools, accept an optional dry_run flag or return a preview diff when blast radius is high, and derive a deterministic idempotency key from (run_id, tool_call_id) before calling external APIs.

Enthaltene Dateien 1

  • SKILL.md