Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Die Beschreibung offenbart wesentliche Seiteneffekte: Änderungen ziehen in noch nicht begonnene Wartungsaufträge nach, während laufende und abgeschlossene unberührt bleiben. Sie stellt zudem klar, dass es sich um eine partielle Aktualisierung handelt („Nur die angegebenen Felder werden geändert“). Das geht deutlich über die Annotationen hinaus.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Drei Sätze ohne Redundanz: Der erste benennt Aktion und Felder, der zweite die Seiteneffekte, der dritte die partielle Update-Logik. Jeder Satz trägt zur korrekten Nutzung bei.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Für ein komplexes Werkzeug mit 18 Parametern sind die Querschnittsregeln (Nachziehen in Aufträge, Partial-Update, Pause/Ende-Verhalten) gut abgedeckt. Ein Hinweis auf das Rückgabeformat oder die Notwendigkeit einer bestehenden Vertrags-ID wäre noch hilfreich, ist aber durch Schema und Kontext teilweise abgedeckt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Die Schema-Abdeckung ist mit 100 % bereits sehr hoch, daher liegt die Basis bei 3. Die Beschreibung fügt mit „Nur die angegebenen Felder werden geändert“ eine übergreifende Semantik hinzu, die für alle Parameter gilt und im Schema so nicht explizit steht.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Die Beschreibung nennt ein spezifisches Verb („Ändert einen Wartungsvertrag“) und listet die betroffenen Felder sowie die Sonderfälle Pause/Beenden auf. Sie grenzt das Werkzeug klar von den Geschwistern wartungsvertrag_anlegen, wartungsvertrag_ansehen und wartungsvertraege_suchen ab.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Der Verwendungszweck ist eindeutig: Änderung eines bestehenden Wartungsvertrags. Es fehlen jedoch explizite Ausschlusskriterien oder Verweise auf Alternativen (z. B. „zum Anlegen nutze wartungsvertrag_anlegen“), was den Score knapp unter die Bestbewertung drückt.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.