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

Die Annotationen decken das Sicherheitsprofil bereits ab (readOnlyHint, idempotentHint, destructiveHint=false). Die Beschreibung ergänzt darüber hinaus wertvollen Kontext: fail-closed-Verhalten und die Einschränkung auf Objekte der eigenen Scopes. Details zu Rückgabeformat oder Pagination fehlen, sind aber bei einem rein lesenden Einzelabruf weniger kritisch.

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?

Die Kernaussage steht vorn und ist in wenigen Sätzen verdichtet; Abgrenzung und Fallback folgen logisch. Der angehängte Keyword-Block („EN: end user, customer, portal, notification, map, scope“) trägt für einen Agenten keinen Informationswert und ist verschenkter Platz.

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 Ein-Parameter-Lesetool ist alles Nötige vorhanden: Zweck, Rollenkontext, Sicherheitsverhalten, Abgrenzung zum Geschwister-Tool und der Weg zur udid-Beschaffung. Ein Output-Schema existiert nicht, sodass keine Rückgabebeschreibung erforderlich ist.

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-Beschreibungsabdeckung liegt bei 100 %, das Schema dokumentiert den einzigen Parameter id bereits als „Objekt-udid (32-hex)“. Die Beschreibung wiederholt im Wesentlichen nur „ueber seine udid“ und fügt kein zusätzliches Format- oder Semantikwissen hinzu – Baseline 3.

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 konkretes Verb und eine konkrete Ressource („einzelnes Objekt … lesen“) und grenzt das Werkzeug ausdrücklich von onto_object_show ab („inhaltlich identisch … nimm dieses, wenn du als Scope-Nutzer … arbeitest“). Ein Agent kann die beiden Tools ohne Blick in die Schemata unterscheiden.

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?

Die Nutzungsbedingung ist explizit: Verwende dieses Tool als Scope-Nutzer, nicht als Administrator. Zusätzlich wird der Ablauf bei fehlender udid vorgegeben („Ohne udid: ontouser_scope_index, dann die Objektliste“), also sowohl Wann als auch Wie.

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