Telesherpa Ontology Platform

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

Annotations already declare this is a non-readonly, non-idempotent, open-world operation. The description adds concrete behavioral context beyond that: it logs in internally with the given credentials, redeems the voucher, removes the 'notactivated' role, and grants full access. That is valuable operational detail. It does not discuss failure modes or reversibility, keeping it from a 5.

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?

The first sentence is well front-loaded and states the core action. However, the description is bilingual, repeats the voucher-code concept several times, and includes some redundant German sentences. It is informative but not tight, so it earns a middle score.

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?

For a mutation tool with three required parameters, annotations, and no output schema, the description covers the essential context: required credentials, code source, and the resulting account effect. It does not explain error behavior or return values, but the schema and annotations carry enough of that structural load. The description is therefore mostly complete.

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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the voucher as a 7-digit activation code from email and identifies the login fields as the registered account's email and password. This adds some clarity but is largely redundant with the schema, matching the 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?

The description clearly states a specific verb and resource: 'Activate a registered account with the voucher code.' An agent can understand the core action without opening the schema. It does not explicitly differentiate from nearby sibling tools such as register or redeem_invite_code, so it falls short of a 5.

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?

The description gives useful usage context: the code comes after email registration and can be obtained from a human or via IMAP. It also states that login credentials are required. However, it does not explicitly say when to use this tool instead of siblings like register, login, or redeem_invite_code, so guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=false, readOnlyHint=false and idempotentHint=false; the description adds that the operation only appends and 'loescht nichts', reinforcing the non-destructive profile. It does not, however, say what happens when the same address already exists, which matters given the explicit non-idempotent hint.

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?

The core purpose and the alternative routing are front-loaded in the first three sentences, with no redundant restatement. The trailing '| EN: allowlist, permission, whitelist, code' keyword line is search padding rather than agent-relevant information and slightly dilutes an otherwise tight description.

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?

With an output schema absent, three fully documented parameters, and annotations covering the safety profile, the description supplies enough to call the tool correctly. The only meaningful gap is duplicate/conflict behavior for an appended entry, which an agent would want before retrying.

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?

Schema description coverage is 100% and the schema already supplies concrete examples ('hans@firma-x.de', glob wildcards) and pattern_type semantics. The description only restates at a high level that an address or pattern is added, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb (hinzufuegen) and resource (einzelne E-Mail-Adresse/Adressmuster zur Allowlist eines Codes) and scopes it to a single entry. It explicitly distinguishes the tool from upload_code_allowlist (bulk) and delete_code_allowlist_entry (removal), so an agent can select it without opening schemas.

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?

Gives explicit when-to-use ('fuer einzelne Nachzuegler'), names the alternative and its condition ('fuer viele Adressen ... upload_code_allowlist'), and routes removal to delete_code_allowlist_entry. Both exclusions and alternatives are stated, leaving nothing to inference.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description's safety claim is partly redundant. However, it adds valuable return context: the response includes roles, tool counts, next steps, and guide_repo/guide_entry/guide_version. This is useful behavioral detail beyond annotations, with no contradiction.

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?

The purpose and trigger are front-loaded in the first two sentences. The description is slightly longer than necessary, with a repo URL and an English keyword list appended, but these extras do not obscure the main guidance.

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?

Without an output schema, the description must explain what comes back, and it does: roles, tool counts, next step, and guide fields. It also covers the zero-param safety profile via annotations. Nothing critical is missing for an agent to decide and invoke this tool.

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?

There are zero parameters, and the schema is empty, so no parameter semantics are needed. The baseline for a zero-parameter tool is 4; the description does not need to add param details.

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?

The description uses a specific verb ('Zeigt den Auth-Zustand dieser Verbindung') and enumerates exactly what is reported: token validity, roles, and the next step. It is clearly distinct from siblings like login, refresh_access_token, and register, which it names as alternative paths.

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?

It gives an explicit trigger condition: 'Nuetzlich, wenn unerwartet wenige Tools sichtbar sind'. It also names the alternatives (login, refresh_access_token, register) and the outcome of following that path, leaving no ambiguity about when to call this tool.

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

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

Goes beyond the annotations (readOnlyHint=false only signals mutation) by stating that existing tokens remain valid and no re-login is required — genuinely useful post-mutation context. It does not cover failure behavior (wrong old password, mismatch of the two new entries), so not a full 5.

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?

The core content is front-loaded and each sentence carries information (trigger, constraints, scope boundary, post-condition). The bilingual keyword tail "| EN: password, credentials, account" is retrieval padding that adds no instruction value.

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?

With no output schema and a simple 3-param schema, the description supplies the important behavioral envelope (own account only, tokens survive). The open gap is the mismatch between the empty `required` array and the prose calling the fields mandatory — an agent could infer optional inputs.

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?

Schema coverage is 100%, so baseline would be 3, but the description adds cross-field semantics the schema does not express: the old password is mandatory and the new one must be supplied twice identically. Useful, though it doesn't clarify why the schema lists the fields as optional while the text calls them required.

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?

States a specific verb and resource (change the password of one's OWN account) and explicitly bounds scope to the caller's own account, distinguishing it from sibling `onto_user_update`, which it names for account administration. An agent can pick between the two without opening a schema.

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?

Gives the triggering condition ("Nutze es, wenn der Mensch das Passwort wechseln will") and an explicit exclusion with the alternative: foreign passwords cannot be set even by an admin, accounts are managed via `onto_user_update`. That is when-to-use, when-not, and the alternative all in one.

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

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

Annotations already declare non-read-only, idempotent, non-destructive behavior, and the description adds useful context: empty call returns current state, populated call changes fields, and roles are not modified. It does not fully explain partial-update semantics when only some fields are supplied.

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?

The core German description is dense and front-loaded with the key read/change distinction. The appended English keyword string is irrelevant to profile operations and does not earn its place.

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?

For a five-optional-parameter tool with no output schema, it explains the read/update behavior and role boundaries well enough to call correctly. It still leaves partial-update and return-value specifics implicit, and the file/upload keywords blur capability boundaries.

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?

Schema description coverage is 100%, so the schema already documents all five parameters. The description lists the same fields but adds no format details, constraints, or partial-update behavior, making the baseline 3 appropriate.

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?

The first sentence clearly states that this reads or changes the user's own profile fields, and it distinguishes own-profile work from role and foreign-profile operations. However, the trailing English keywords 'file, upload, document, attachment' are unrelated and can mislead about the tool's purpose, so it is not a clean 5.

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?

It gives explicit when-to-use guidance: own profile data, no fields for reading, fields for changing, and it excludes role changes and foreign profiles. The named alternatives onto_user_update and onto_user_update_profile do not appear in the provided sibling list, which reduces actionability.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and non-idempotency, so the mutation profile is covered. The description adds that the code governs what access the redeemer receives and that the code itself must be handed off elsewhere rather than recorded here. It does not state whether repeated calls with the same label create duplicates or what the response contains, which would be the higher-value addition for a create tool.

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?

Purpose is front-loaded in the first sentence, but the definition is padded: the 'Weg (b) | Die Einladung geht in beide Richtungen' passage is vague and off-topic, and the 'EN: invitation, invite, voucher, code, bundle' keyword tail is search metadata rather than agent guidance.

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?

For a 10-parameter create tool with full schema coverage and no output schema, the description supplies the purpose, the permission dimension, the handoff rule and the two sibling routes, which is close to sufficient. It would be complete with a note that the created code is returned by the call and a hint about the can_manage_scope prerequisite.

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?

Schema description coverage is 100%, and the schema already explains kind, max_uses, unlimited, expires_days and the permission flags in detail. The description adds nothing about individual parameters beyond the general 'der Code steuert, welchen Zugang der Beitragende erhaelt'. With the schema doing all the work, the baseline 3 applies.

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?

The first sentence gives a concrete verb+resource (create an invite code) plus its effect: new members can self-register and the code determines the access the redeemer gets. Siblings are named explicitly (list_invite_codes, revoke_invite_code), so the boundary is visible. However, the trailing 'Weg (b)' sentence about inviting people/agents into your scope after setup describes a different workflow and blurs what this tool actually does.

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?

Explicit when-to-use ('Nutze es zum Anwerben von Mitgliedern/Subunternehmern') and explicit routing to alternatives for the adjacent tasks: manage with list_invite_codes, invalidate with revoke_invite_code. It also warns not to store the code here. The only gap is that the ambiguous 'Weg (b)' paragraph reads like an alternative usage without saying when that path applies.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious context: only the allowlist admission is affected and already-registered accounts remain untouched — this is exactly the kind of side-effect disclosure an agent needs before a destructive call. It omits whether the action is reversible or what happens if the ID no longer exists (relevant given idempotentHint=false).

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?

Sentences are short, front-loaded, and behaviour-first (what is removed, what survives, when to use it, alternative). The trailing "EN: allowlist, permission, whitelist, code" keyword block is search padding rather than agent-useful content and slightly dilutes an otherwise tight definition.

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?

For a one-parameter destructive tool with no output schema, the description covers scope, non-effect on registered accounts, and the sibling alternative. The notable remaining gap is failure behaviour / permissions, which matters because the operation is explicitly non-idempotent.

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?

Schema coverage is 100% and the id parameter already documents its own origin ("aus list_code_allowlist"). The description adds no further detail about the parameter, so this is the standard baseline-3 case where the schema carries the burden.

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?

States a specific verb (entfernen/delete) and a specific resource (an entry in a code's allowlist), and explicitly contrasts scope with upload_code_allowlist, which replaces the whole list. An agent can distinguish this from add_code_allowlist_entry and upload_code_allowlist without opening any schema.

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?

Gives a clear use case ("Nutze es, um einzelne Adressen zu sperren") and names the alternative for a different intent (bulk replacement via upload_code_allowlist). It stops short of stating when this tool should NOT be used (e.g. blocking a whole domain), but the routing signal is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Rein lesend' is largely redundant. The description does add value beyond them by disclosing the return shape ('als Rohdatei') — raw file bytes rather than metadata — which matters because there is no output schema. It stops short of covering auth requirements or what happens on an invalid token.

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?

The core capability and the identifier prerequisite are front-loaded in the first two sentences, with exclusions following. The trailing '| EN: get, document' machine-generated tag is low-value noise and the bilingual phrasing adds slight friction, but overall there is little waste.

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?

For a two-parameter read tool with full schema coverage and rich annotations, the description covers purpose, prerequisites, sibling routing, and the raw-file return nature. The main residual gap is error/edge-case behavior for a bad slug or token, which is minor given how much structured data already exists.

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?

Schema description coverage is 100%, so both parameters are already documented, and the description only restates that the call is made 'ueber urlslug und filetoken'. It adds no format, provenance, or validation detail beyond the schema baseline.

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?

States a specific verb and resource ('Ein Dokument (PDF, Office-Datei) ... als Rohdatei abrufen') plus the exact lookup keys (urlslug, filetoken). It actively distinguishes itself from siblings by naming get_image for images and upload_file_to_object for uploads, so an agent can route correctly without opening schemas.

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?

Explicit when-to-use ('Nutze es, wenn du die beiden Kennungen hast'), explicit alternatives for adjacent cases (get_image for images, upload_file_to_object for uploads), and it tells the agent where the identifiers come from (onto_object_show). That is the full when/when-not/where-from triad.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations, including that the result is a raw file and that filetoken is mandatory for access.

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?

The description is front-loaded and efficient, with the core action and prerequisites stated first. Some wording is redundant with annotations, such as 'Rein lesend', but the rest is purposeful.

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?

For a simple two-parameter read tool with full schema coverage and rich annotations, the description is complete: it explains the raw-file return, required identifiers, identifier provenance, and the upload alternative.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by clarifying that urlslug and filetoken are identifiers found on objects or structured image storage, and that filetoken is essential to retrieve the file.

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?

The description states a specific verb and resource: retrieve an image as a raw file using urlslug and filetoken. It also explicitly distinguishes the tool from upload_file_to_object, so an agent can identify its purpose without opening the schema.

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?

It gives clear usage conditions: use it when both identifiers are available, note that filetoken is required, and explain that the identifiers come from onto_object_show or onto_file_structured. It also explicitly names upload_file_to_object as the alternative for uploading.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope context by specifying that the notifications belong to the logged-in account, though it does not describe return format or pagination behavior.

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?

The description is front-loaded with the core action and scope, then immediately routes the agent to the right alternatives. The extra English keyword line is compact and useful for search/retrieval without obscuring the main instruction.

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?

For a zero-parameter, read-only notification retrieval tool with rich annotations, the description covers purpose, scope, and alternatives well. It could add a little more about what the notification result contains, but no output schema exists and the core invocation context is complete.

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?

The tool takes zero parameters, so the baseline is 4 under the rubric. The description does not need to explain parameter semantics, and no parameter-related ambiguity is introduced.

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?

The description states a specific verb and resource: retrieving the logged-in account's own notifications. It also explicitly distinguishes this tool from ontouser_notification_index, ontouser_notification_read, and onto_action_logs, so an agent can identify its exact role among siblings.

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?

It gives clear when-to-use guidance ('Nutze es, um neue Meldungen zu finden') and names alternatives with conditions: ontouser_notification_index for scope-user self-service, ontouser_notification_read for marking as read, and onto_action_logs for admin system logs.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Kein Schreibpfad' is largely redundant. What the description does add beyond structured data is the list of returned fields, valuable since there is no output schema. Missing: auth prerequisites and what happens if the profile is incomplete.

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?

Two short sentences, read-only constraint front-loaded, with the returned fields immediately after. The bilingual duplication is slightly redundant but serves keyword discovery rather than bloating the semantics.

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?

For a parameterless read tool with full annotation coverage, the description covers the only real gap by enumerating the returned fields in place of a missing output schema. Nothing an agent needs in order to call it correctly is absent.

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?

The tool takes zero parameters, so there is nothing to disambiguate and the baseline is 4. The description correctly implies a no-argument call that returns the caller's own profile.

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?

States a specific verb and scope ('Eigenes Profil rein lesend abrufen') plus the exact fields returned (Name, E-Mail, Organisation, Notizen, Skills), so the agent knows precisely what it gets. It signals read-only intent ('Kein Schreibpfad'), which implicitly separates it from change_profile/change_password, but never names those siblings explicitly.

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?

The phrases 'Eigenes Profil' and the alias line 'who am i, my account, profile' give clear situational triggers, and 'Kein Schreibpfad' tells the agent this is not the tool for edits. It stops short of naming change_profile as the alternative for mutations, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered; "Rein lesend" largely restates that. The description adds no operational context such as auth requirements, pagination, or what happens when no allowlist exists, so it stays at the baseline for an annotated read tool.

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?

The operational content is front-loaded and every clause carries information (action, scope, read-only nature, sibling routing). The trailing keyword line ("EN: allowlist, permission, whitelist, code") is retrieval-oriented padding rather than task guidance, slightly diluting an otherwise tight description.

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?

For a single-parameter read tool with no output schema, the description covers the scope, the read-only nature, and where the related mutation tools live. It does not describe the returned entry format or ordering, a minor gap for a listing tool whose single parameter is already fully documented.

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?

Schema description coverage is 100% and the schema itself explains that an empty list means anyone may redeem the code. The description adds nothing about code_id format or lookup beyond what the schema already provides, so the baseline 3 applies.

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?

States a specific verb and resource: reading the e-mail allowlist of an invitation code, and clarifies what the list contains (which addresses/patterns are permitted). It also names the three sibling tools that handle the mutation/upload cases, so an agent can distinguish it without opening another schema.

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?

Explicitly says to use it as the current state before making changes, and routes the alternative operations to add_code_allowlist_entry, delete_code_allowlist_entry, and upload_code_allowlist. There is no explicit when-not-to-use statement, but the routing is clear enough to select correctly.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely new context: visibility is scope-limited and fail-closed, so an agent knows results may be empty by design rather than by error. Return-shape disclosure is also present, though pagination/limits are not mentioned.

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?

The core guidance (what it returns, use the udid next, scope-limited) is front-loaded and easy to scan. The trailing '| EN: list, formdefs' bilingual tag is redundant given the title and slightly dilutes the otherwise efficient structure.

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?

With no output schema and no parameters, the description carries the full burden and does so: it enumerates the return fields, explains the visibility rule, and links to the follow-up tool. An agent has everything needed to call it correctly and interpret an empty result.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. Schema coverage is 100% and empty, and the description correctly does not invent parameter semantics.

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?

States a specific verb+resource (list all visible formdefs) and enumerates the returned fields (udid, title, field count, per-field key/label/widget/required), which an agent can distinguish from sibling show_formdef. The scope constraint (only forms in your scopes, fail-closed) further sharpens what 'list' means here.

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?

Explicitly positions itself as the FIRST STEP for choosing the right form and tells the agent to take the udid to show_formdef, giving a clear use context and a named downstream tool. It stops short of naming exclusion conditions versus adjacent siblings like onto_formdef_list_templates, so it is not a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces the read-only nature. It also adds useful behavioral context that the listing shows who was invited and whether the code is still valid. It does not describe pagination or return format, but those gaps are minor for a simple read-only list.

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?

The description is front-loaded with the core purpose and followed by useful routing information to sibling tools. It is mostly efficient, though the appended bilingual keyword list is more search-oriented than explanatory.

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?

For a simple, one-parameter list tool with annotations covering safety and idempotency, the description provides enough context to select and invoke it correctly. It gives a basic sense of the returned information, though it could say more about the exact return structure since there is no output schema.

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?

There is only one parameter, scope_id, and the schema description coverage is 100%, so the schema already explains its meaning and the required permission. The description does not add further parameter-specific detail beyond what is already in the schema, making the baseline score appropriate.

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?

The description uses a specific verb and resource: it lists the user's own invite codes and indicates whether each code is still valid. It also clearly distinguishes this tool from create_invite_code, revoke_invite_code, and list_code_allowlist by naming the sibling tools.

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?

It explicitly says when to use the tool: to find a code for sharing or revocation. It also names alternatives for creating a new code, revoking a code, and viewing a code's email allowlist, leaving little ambiguity about tool selection.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Rein lesend' adds no information beyond structured data. The one genuinely useful behavioral note — that scope_id requires can_manage_scope=1 and that results contain only email, rights and sp_id — lives in the schema, not the description. With annotations covering the safety profile, the description carries only modest extra context.

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?

The core content is two tight sentences with the action and read-only nature front-loaded, followed by compact alternative routing. The trailing '| EN: member, participant, membership, team' keyword list is slight padding for a human reader, though it aids retrieval matching.

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?

For a two-parameter filtered list with no output schema, the definition covers purpose, safety, and all three adjacent operations, and the schema fills in the authorization requirement and the narrow return payload. Pagination behavior (20 per page) is documented in the schema rather than the description, which is acceptable given full schema coverage.

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?

Schema description coverage is 100%: page (20 per page, default 1) and scope_id (requires can_manage_scope=1, returns only email/rights/sp_id) are both fully documented in the schema. The description itself says nothing about either parameter, so baseline 3 applies.

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?

States a specific verb (auflisten) and resource (Mitglieder eines eigenen Bereiches) with an explicit scope qualifier ('eigenen'), and adds English synonyms (member, participant, membership, team) that disambiguate the concept. An agent can distinguish it from scope-level siblings like ontouser_scope_index without opening a schema.

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?

Names three concrete alternatives with their triggering conditions: toggle_member_flag for rights changes, remove_member for removal, create_invite_code for inviting. It also gives a positive usage motive ('Ist-Stand vor Aenderungen sehen'), so both when-to-use and when-to-use-something-else are covered.

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

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

Adds substantial context beyond the annotations: token lifetimes (10h access, 30d refresh), the fact that the response is delivered only once and must be persisted immediately, and the fallback path when renewal fails. This is exactly the operational knowledge the readOnlyHint/idempotentHint flags cannot convey.

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?

Front-loaded with the core exchange and token lifetimes, with error branches in descending priority. Slightly redundant: the persist-both-tokens and use-refresh_access_token advice is repeated near the end, and the trailing EN keyword list is filler.

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?

There is no output schema, and the description compensates by naming exactly what is returned (access_token + refresh_token, once only), plus lifetime and persistence requirements. Nothing an agent needs to call this correctly is missing.

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?

Schema coverage is 100% and already maps client_id to username/email and client_secret to password/secret, so the description adds little on these two fields. It does clarify the OAuth framing (grant_type=refresh_token for the sibling), but that concerns renewal, not this tool's own parameters.

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?

States a concrete verb+resource: exchange client_id/client_secret for access_token + refresh_token. It explicitly distinguishes itself from register (account creation) and refresh_access_token (renewal), so an agent can route correctly without opening other schemas.

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?

Gives explicit when-to-use (once at the start), when-not (do NOT log in again; use refresh_access_token, which needs no password), the prerequisite (register first if no account), and the out-of-scope case (forgotten password is done by a human via the web UI, no tool exists).

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

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

Beyond the destructive/idempotent annotations, the description adds useful behavioral context: the required permission scope and that this removes a button/action definition. It does not contradict annotations; it simply does not discuss side effects such as cascading removal or missing-key behavior.

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?

The definition is short and front-loads the operation, followed by permission information and search keywords. The trailing bilingual keyword list is somewhat incidental, but it does not bloat the definition.

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?

For a one-parameter destructive delete with full annotations and a documented schema, the description provides enough context: operation, object, and authorization. It omits some edge-case behavior, but the annotations and schema already cover the main safety profile.

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?

Schema description coverage is 100%, with the single 'key' parameter documented as 'Schluessel der Actiondef'. The description adds no extra parameter semantics beyond that schema coverage, so the baseline of 3 applies.

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?

The description opens with a specific verb-resource pair, 'Actiondef loeschen' (delete action definition), and adds 'Button entfernen' to clarify the object. It is clearly a deletion operation, though it does not explicitly name sibling tools such as onto_actiondef_save or onto_actiondef_list.

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?

It states the required authorization ('Scope-Manager/Schreiber', can_manage_scope/can_write), which tells the agent the prerequisite for using it. It does not spell out when-not to use it or explicitly compare it with siblings, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, and the description's 'Rein lesend' merely restates that. The genuinely additive content is workflow-related (the returned key feeds onto_object_execute_action) rather than behavioral – nothing about result ordering, pagination semantics, or what fields a definition contains beyond the button metaphor.

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?

The core purpose, read-only note, usage trigger and alternatives are front-loaded and compact. The trailing bilingual keyword block ('| EN: action, button, definition, gate, condition, rule') is somewhat extraneous but short and clearly demarcated as a search tag line.

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?

With only two optional paging parameters, full schema coverage, no output schema and safety covered by annotations, the description supplies everything needed to decide and call correctly: what is listed, that it is a read, and how the result is used. Only the shape of returned entries is left implicit.

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?

Schema description coverage is 100%, so both 'page' and 'limit' are already documented, including the session-wide scope of limit. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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?

States a specific verb and resource ('die nutzbaren Action-Definitionen auflisten') and immediately clarifies the domain meaning ('welche Buttons an welchen Objekten erscheinen'). It also distinguishes itself from sibling tools onto_actiondef_save (create/modify) and onto_object_execute_action (consumes the key), so an agent can pick it without opening schemas.

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?

Explicit when-to-use: 'Nutze es, wenn du wissen willst, welche Aktion du auf einem Objekt ausfuehren kannst'. It names the downstream consumer ('den key uebergibst du an onto_object_execute_action') and the alternative for mutation ('Anlegen/Aendern: onto_actiondef_save'), covering both routing decisions.

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

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

Annotations already declare destructive/idempotent/non-read-only, but the description adds substantial behavioral context beyond them: authorization failure modes (403 with guard message, 400 without person binding), scope-based visibility vs execution distinction, the result_scope_id 'bridge' that lets a read-only user write a restricted property set, hidden_actions suppression by scope managers, and the warning that two scopes must exist to reach the write scope. This is exactly the kind of non-obvious behavior annotations cannot express.

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?

The essential requirements are front-loaded and most sentences carry unique information, but the text is very long, mixes German and English, and contains a garbled keyword fragment ("| EN: action, button, definition, gate, condition, rule action.result_scope_id") that runs into the next idea and is hard to parse. The 'MerkSATZ' and two full examples push length well past what a scanning agent needs.

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?

For a complex, permission-gated mutation with no output schema, the description covers nearly everything an agent needs: required body fields, scope rights, admin-only flags, guards, result_scope_id, and worked examples. Minor gaps remain — it does not say whether an existing definition with the same key is overwritten or whether key is immutable, which matters for an upsert-style save.

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?

Schema coverage is 100% and already documents key/label/body, yet the description still adds real meaning: body.scopes is mandatory, exactly one target scope at creation, public:true restricted to admins, action.type 'form_answer' semantics, required person binding placeholders, and the 'update' case requiring action.props. It supplies two concrete body examples that the schema's single truncated example does not cover.

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?

The description opens with a specific verb+resource phrase: "Actiondef anlegen/aendern (Button am Objekt)", which tells an agent it creates/updates an action definition that renders as a button on objects. It never names its siblings (onto_actiondef_list, onto_actiondef_delete), so the create/update vs list/delete distinction is implied by the verb rather than stated.

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?

It states the hard precondition clearly (body.scopes with the scope IDs is PFLICHT, caller must be can_manage_scope or can_write there, otherwise 403) and gives an explicit exclusion (PUBLIC scope 15 and public:true are admin-only). It also explains a legitimate alternative usage path (a scope manager copying a platform action into their own scope). What it lacks is explicit routing to sibling tools for the adjacent operations.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds valuable specifics: it overwrites existing type definitions, the previous value is gone, and there is no history or undo. This directly tells the agent what gets destroyed, beyond the binary flags.

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?

The purpose and the critical destructive warning are front-loaded, and the description is compact. There is mild redundancy between "kann bestehende Typdefinitionen ueberschreiben" and "Der bisherige Wert ist danach weg (keine Historie, kein Undo)", but overall it is efficient.

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?

For a destructive mutation tool with rich annotations and full schema coverage, the description covers the prerequisite check, the consequence of overwriting, and the undo route. It does not describe any return value, but with no output schema this is a minor gap.

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?

Schema description coverage is 100%, so both parameters are already documented. The description does not add meaning beyond the schema and even uses the singular "ein Preset" while the schema clarifies that multiple presets are allowed (an array). The baseline of 3 applies because the schema carries the parameter semantics.

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?

The description states a specific verb+resource ("Ein Preset auf einen Scope anwenden") and the effect ("dessen Objekttypen anlegen/aendern"). It distinguishes itself from siblings by naming onto_catalog_index as the prerequisite and onto_catalog_clear as the undo path, though it does not explicitly contrast with onto_catalog_presets.

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?

It gives a clear prerequisite ("Pruefe vorher mit onto_catalog_index, was enthalten ist") and names the undo alternative ("Rueckgaengig: onto_catalog_clear"). It does not state explicit when-not conditions, but the context is sufficient to select this tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the concrete consequence that annotations cannot express: existing objects of those types become unreachable, plus the pre-flight check to perform. This is exactly the extra context the bar for annotated tools asks for.

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?

The warning and the sibling alternative are front-loaded and every sentence carries information. The trailing '| EN: catalog, preset, template, apply, clear' keyword list is search-oriented padding rather than instruction, which is a minor efficiency loss.

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?

For a single-parameter destructive mutation with no output schema and full annotation coverage, the description supplies the risk, the recovery relationship to apply, and the escape hatch. Nothing an agent needs to call it safely is missing.

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?

Only one parameter (scope_id) and schema description coverage is 100%, so the schema already documents it. The description adds no further meaning about scope semantics or format; baseline 3 applies.

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?

States a specific verb (remove/clear) and resource (preset-created object types of a scope), and implicitly anchors it against the apply/create side of the catalog workflow. An agent can tell exactly what class of operation this is without opening the schema.

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?

Explicitly names the intended use case (undoing onto_catalog_apply), the safer alternative for narrow cases (onto_type_delete for individual types), and the precondition check (onto_object_index) to run first. When-to-use, when-not-to-use, and alternatives are all present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'Rein lesend' mostly repeats structured data. The description adds useful workflow context (preview before apply) but says nothing about output shape or size, which is the main remaining behavioral unknown.

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?

The core purpose and the pre-apply guidance are front-loaded in one compact sentence. The trailing EN keyword list ('catalog, preset, template, apply, clear') is slightly noisy and mixes in sibling concepts like apply/clear, but it does not obscure the main instruction.

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?

For a zero-parameter, read-only catalog listing, the description covers what the tool returns conceptually (which types are in which presets), how it relates to apply/clear/presets siblings, and when to use it. Missing only explicit return-shape detail, which is not critical here.

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?

The tool takes zero parameters, so parameter semantics are trivially satisfied. The description does not need to explain any arguments.

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?

The description gives a specific verb and resource: reading the object-type catalog (which types are bundled in which presets). It also explicitly contrasts with the sibling that lists presets (onto_catalog_presets), so an agent can distinguish them without inspecting schemas.

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?

It states a concrete use case: check what a preset contains BEFORE applying it, and points to onto_catalog_presets for listing available presets. It lacks explicit when-not-to-use guidance, but the pre-apply workflow is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "Rein lesend" largely restates structured data. The one piece of added value is characterizing the payload as prepared type bundles intended for selection, but nothing is said about volume, pagination, or scope prerequisites.

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?

Front-loaded with purpose, then usage, then sibling routing — a sensible order with no filler sentences. Minor deductions for the redundant "Rein lesend" (already in annotations) and the trailing keyword list ("catalog, preset, template, apply, clear"), which is search-tag noise rather than agent guidance.

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?

For a zero-parameter read-only list tool with full annotation coverage and no output schema, the description supplies the essential context: what a preset is, why you'd list them, and which sibling to use next. Only the shape/size of the returned list is left unstated, which is acceptable absent an output schema.

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?

The tool takes zero parameters, so the baseline is 4 and there is nothing in the schema the description needs to compensate for. No meaningless parameter prose was added.

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?

Specific verb ("auflisten") plus specific resource ("Objekttyp-Presets"), with an inline definition of what a preset is ("vorbereitete Typ-Buendel zur Auswahl") so the agent doesn't need prior domain knowledge. It is clearly not onto_catalog_apply or onto_catalog_index, though that separation is carried mainly by the routing sentences rather than the purpose statement itself.

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?

Explicit entry-point guidance ("Nutze es als Einstieg, wenn ein Scope mit Standardtypen ausgestattet werden soll") plus direct routing: apply via onto_catalog_apply, inspect contents via onto_catalog_index. The agent knows both when to call this and where to go next, with no inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Rein lesend' largely restates structured data. The description contributes the useful framing that this is a pre-flight check for a pay-per-use account, but discloses nothing about the returned balance format, currency, or freshness. With annotations carrying the safety profile, a 3 is appropriate.

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?

The core instruction is front-loaded in the first three clauses with no waste. The trailing '| EN: credit, balance, pricing, billing, top-up, checkout' is keyword stuffing rather than descriptive content, which costs it the top score.

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?

For a zero-parameter, read-only check with no output schema and rich annotations, the description covers everything an agent needs: what it returns conceptually, when to call it, and where to go for the related operations.

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?

The tool takes zero parameters, so there is nothing for the description to document and the baseline is 4. The description claims nothing about inputs, which is consistent with the empty schema.

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?

States a specific verb and resource ('das aktuelle Credit-Guthaben abrufen') and qualifies the account type (Pay-per-Use). It explicitly separates itself from three named siblings (onto_credit_pricing, onto_credit_chargeup, onto_credit_checkout), so an agent can pick it without opening any schema.

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?

Gives an explicit when-to-use condition ('vor kostspieligen Aktionen pruefen, ob Guthaben vorhanden ist') and routes the agent to the correct alternatives: pricing for cost lookup, chargeup/checkout for topping up. Nothing is left to inference.

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

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

Adds real value beyond the annotations: it states that actual money moves / a payment is triggered, and warns that the amount is a payment rather than a refund. That is consistent with openWorldHint=true and destructiveHint=false and reinforces the billing-risk profile. It stops short of describing what happens to an invalid code or whether failures leave partial state.

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?

The warning and the purpose are front-loaded, followed by alternatives and next state in a logical order. The trailing "| EN: credit, balance, pricing, billing, top-up, checkout" tag block is keyword padding rather than actionable information.

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?

The money-movement risk, gating condition, alternatives, and follow-up tool are all covered, which is the important part for a non-idempotent billing mutation. But with required=[] and two distinct modes, the agent is left without guidance on which parameter to supply in which situation, a meaningful gap for this tool.

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?

Schema coverage is 100% and each parameter is already documented (admin-only credits, agent self-service prepaid code), so the baseline is 3. The description only adds the clarification that the amount is a payment, not a refund. It never explains how the two parameters select different modes or that neither is required.

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?

"Credits aufladen (Guthaben erhoehen)" gives a concrete verb and resource that reconcile the ambiguous name/title pair (chargeup vs. Redeem Prepaid Code). It names sibling payment tools, so the agent can place it in the billing family. It does not, however, distinguish the two operating modes implied by the parameters (manual admin top-up vs. prepaid code redemption).

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?

Explicit gating: "nutze es nur auf ausdrueckliche Ansage" tells the agent this requires user instruction before invocation. It also names the alternative paths (onto_credit_checkout, onto_credit_create_prepaid) and the follow-up tool (onto_credit_balance), which is exactly the routing information needed.

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

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

Annotations already indicate a non-readonly, non-idempotent, open-world operation. The description adds important behavioral context by stating that a payment process is triggered and that it should only be executed on explicit command. It does not detail failure modes or whether external payment confirmation is asynchronous, but it substantially improves safety awareness beyond the annotations.

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?

The description is compact and front-loads the action and the safety constraint. The trailing EN keyword list is useful for search but slightly less relevant to invocation, keeping it just below the top score.

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?

Given one required parameter, no output schema, and annotations covering safety traits, the description is largely complete: it explains the action, cautions execution, points to alternatives, and suggests balance checking for success. It could say more about what a successful checkout returns or whether follow-up confirmation is required, but the essential invocation context is present.

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?

Schema description coverage is 100%, and the single parameter 'credits' is already documented in the schema with its EUR conversion. The description does not add parameter-level meaning beyond what the schema provides, so the baseline score for high coverage is appropriate.

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?

The description states a specific action and resource: purchasing credits via checkout, explicitly framed as starting a payment process. It also names sibling tools for related credit operations, so an agent can distinguish this from chargeup, prepaid creation, and balance checking without opening schemas.

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?

It gives an explicit execution condition: only run on explicit instruction. It also routes the agent to alternatives for direct top-up (onto_credit_chargeup) and prepaid quotas (onto_credit_create_prepaid), and points to onto_credit_balance for checking success.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive behavior, so the safety profile is covered. The description still adds genuine business context the annotations cannot carry: flat users (billing_model=flat) incur no credits, and the conversion rate of 1 credit = 0.01 EUR, which the agent needs to interpret results.

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?

The core meaning is front-loaded in one sentence, followed by the flat-model exception and the EUR conversion, both of which earn their place. The trailing "| EN: credit, balance, pricing, billing, top-up, checkout" is keyword padding that adds no semantic value and slightly dilutes the structure.

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?

With no parameters, no output schema and full annotation coverage, the description supplies what is needed: what the tool reports, that output is per-operation credit costs, and the pricing semantics. What is missing is minor — it does not say whether the list is static or reflects the account's current plan.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter claims are made or needed.

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?

"Zeigt, wie viele Credits jede Operation verbraucht" names a specific verb (show) and resource (credit pricing per operation), which is clearly distinct from the sibling balance/chargeup/checkout tools. It does not explicitly name those siblings, so an agent must infer the distinction from the name alone.

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?

Usage is only implied: the agent can infer this is the lookup tool for pricing information, and the flat-model note hints at when the answer is zero. There is no explicit statement of when to use this versus onto_credit_balance, onto_credit_checkout or onto_credit_receipt, all of which sit in the same domain.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real behavior beyond them: only the caller's own receipt is accessible, foreign and nonexistent order numbers are indistinguishable (same 404, an anti-enumeration property), and card token/BIN are withheld from output. These are meaningful disclosures an agent could not infer from annotations.

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?

Front-loaded with the action and returned fields, and the important scoping/404 caveat follows quickly. The trailing bilingual keyword list ('EN: credit, receipt, invoice...') is retrieval padding that dilutes an otherwise tight description.

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?

For a single-parameter read tool with no output schema, the description supplies the returned-field list, the error semantics, the data-redaction guarantee, and where to source the ID — everything needed to call it correctly, with annotations covering safety.

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?

Schema description coverage is 100% and the schema already explains that order_id is the chargeup:sumup row from onto_credit_balance. The description restates this same origin, adding little new syntax or format detail beyond the schema, so the baseline 3 applies.

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?

States a specific verb + resource ('Beleg ... lesen') and enumerates exactly what the receipt contains (Bestellnummer, Datum, Betrag, Credits, Status, Transaktion, Zahlungsdaten). This clearly separates it from onto_credit_balance (balance), onto_credit_chargeup (top-up), and onto_credit_checkout.

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?

Tells the agent where to obtain the required order_id ('Die Bestellnummer steht in onto_credit_balance'), which is actionable routing to a sibling. It also clarifies that foreign/nonexistent IDs yield the same 404, but it does not explicitly name which sibling to use for other receipt-adjacent needs (e.g. balance vs. chargeup).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the non-obvious behavioral trait that triggers are queued and processed on 60 s / 5 min cycles, explaining why results may be stale and discouraging duplicate writes. It does not add anything about the shape or freshness of the returned data beyond the category list.

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?

The most useful information is front-loaded (what the status contains) followed by the queue timing that explains why the tool matters. It is slightly padded by 'Genau deshalb ist dieses Werkzeug da' and by the bilingual split, where the English portion is only a keyword tag rather than full explanatory text.

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?

With zero parameters, no output schema, and annotations covering safety, the description carries exactly the burden it must: what it reports, why results lag, and when to call it instead of retrying. An agent has everything needed to select and invoke it correctly.

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?

The tool takes zero parameters, so the baseline applies and no parameter meaning is needed. The description correctly presents the tool as unfiltered/global, but adds no additional parameter-level detail because there is none to add.

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?

The description names a specific resource and scope: backlog and health of the automation, listing what it surfaces (open events, errors, last runs). The EN keyword tail ('automation queue, trigger status, backlog, last runs') reinforces this. It is somewhat abstract in the German framing ('Rueckstand und Gesundheit der Automatik'), but an agent can tell it apart from the onto_trigger_create/update/delete/index siblings.

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?

It gives explicit when-to-use guidance: check here after creating or changing a rule rather than repeating the action or blocking on a result. It also supplies the when-not rationale ('instead of repeating the action or waiting'), which is precisely the routing decision an agent gets wrong with asynchronous triggers.

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

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

Beyond the annotations, it discloses that the tool only affects the caller's own account, does not change object data, and creates a new entry on every call even for the same URL. The duplicate-creation warning directly reinforces the non-idempotent behavior declared in annotations.

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?

The main purpose and constraints are front-loaded, and the removal route is kept short. It is slightly verbose because the duplicate warning is restated across two sentences and the English keyword tag is appended, but no sentence is seriously off-topic.

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?

For a two-parameter favorite-add tool with no output schema, the description gives the necessary scope, mutation boundary, duplicate risk, pre-check guidance, and removal alternative. The minor reference to a saved filter is not enough to make the definition incomplete.

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?

Schema description coverage is 100%, so the schema already explains both url and title. The description adds useful parameter-relevant meaning by clarifying that repeated use of the same URL is not treated as the same favorite and can produce duplicates.

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?

The description states a specific verb and resource: adding an object to the user's own favorites. It also explicitly distinguishes the action from object mutation and from removal, so an agent can tell what it does without opening the schema.

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?

It says to use the tool for frequently used objects, warns to check onto_favorite_index first to avoid duplicates, and names onto_favorite_delete for removal. These are explicit when-to-use and alternative-routing instructions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false. The description adds real context beyond them: destruction is confined to the bookmark, the underlying object is untouched, and the effect is limited to the caller's own account.

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?

Short, front-loaded sentences with the scope constraint stated first. The trailing '| EN: favorite, bookmark, quick access' keyword tag is a small amount of padding but serves discoverability, so the cost is minor.

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?

For a single-parameter idempotent delete with strong annotations and no output schema, the description covers what is destroyed, what survives, whose account is affected, and where to go for object deletion. Only the toggle sibling relationship is unaddressed.

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?

Schema coverage is 100% and the single 'id' parameter is already documented as a favorite ID sourced from onto_favorite_index. The description adds no further meaning about the parameter, so the baseline 3 applies.

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?

The description names a specific verb ('entfernen') and resource ('aus den eigenen Favoriten') with clear scope. It explicitly separates itself from onto_object_delete and, by implication, from onto_favorite_add, so an agent can pick it without opening schemas.

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?

It states the crucial when-not condition ('Loescht NUR die Merkung, nicht das Objekt selbst') and routes object removal to onto_object_delete. What is missing is disambiguation against the close sibling onto_favorite_toggle, which could also remove a favorite.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful account scoping by saying 'gemerkte Objekte des angemeldeten Kontos' and repeats that it is read-only, but it does not describe return format or pagination behavior.

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?

The definition is front-loaded with the core purpose and then routes the agent to alternatives efficiently. The trailing English keyword line ('EN: favorite, bookmark, quick access') is slightly extraneous for invocation, but the overall structure is compact and useful.

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?

For a zero-parameter list tool with rich annotations and no output schema, the description provides enough context: it identifies the resource, the account scope, the read-only nature, and the relevant sibling alternatives. Nothing critical is missing for correct invocation.

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?

This tool has zero parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter tool is 4, and the description appropriately does not invent parameter details.

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?

The description uses a specific verb and resource: 'Die eigenen Favoriten auflisten' and clarifies that these are saved objects of the logged-in account. It also distinguishes the tool from sibling operations by naming onto_favorite_add, onto_favorite_delete, and onto_object_index.

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?

It explicitly states the use case: quickly accessing frequently used objects. It also gives concrete alternatives for adding, removing, and listing all objects, leaving little ambiguity about when to choose this tool versus its siblings.

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

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

Goes well beyond the annotations by disclosing the branching side effect (existing favorite is DELETED, otherwise created), the scope limit ('wirkt nur auf das eigene Konto'), and the reversibility (a second identical call undoes the first). This reconciles with destructiveHint=false and idempotentHint=false — the deletion is self-reversible, so no annotation contradiction, and the description supplies the context the annotations lack.

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?

Front-loads the core behavior, then the caveat, then the guidance — a logical order with no wasted sentences. Minor deductions for the bilingual duplication and the trailing keyword tag ('| EN: favorite, bookmark, quick access'), which is padding rather than information.

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?

For a two-parameter mutation with full schema coverage and no output schema, it covers state dependence, scope, reversibility, and alternatives — everything needed to call it safely. It stops short of saying what the return value reports (e.g. the resulting state), which would have made the round-trip behavior fully predictable.

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?

Schema description coverage is 100%, so both parameters (url required, title optional with a stated default) are already fully documented. The description only implies that the URL is the identity used for the toggle; it adds no format, normalization, or matching semantics beyond the schema. Baseline 3 applies.

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?

States a specific verb and resource pair — toggling the favorite status of an object ('Favoriten-Status eines Objekts umschalten') — and disambiguates from siblings by naming onto_favorite_add and onto_favorite_delete. An agent can distinguish it from the add/delete variants without opening any schema.

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?

Gives an explicit selection rule: use this when you do not know the current state, because no pre-read is needed; use onto_favorite_add to add deliberately or onto_favorite_delete to remove deliberately. Both the use case and the alternatives are spelled out.

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

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

Beyond the destructiveHint and idempotentHint annotations, the description adds that deletion is irrevocable, that only the file is removed while the object record remains, and that replacement is done by re-uploading. These are meaningful consequences and match the annotations.

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?

The purpose and irreversibility warning are front-loaded, followed by the deletion scope and replacement path. The compact EN keyword tag is ancillary but does not obscure the operational content.

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?

For a destructive file deletion tool with full schema coverage and rich annotations, the description covers the key agent-relevant facts: irreversibility, reference-check prerequisite, exact deletion scope, and replacement workflow. No output schema exists, so return-value explanation is not required.

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?

Schema description coverage is 100%, so file_id and file_udid are already documented in the schema. The description does not add parameter-specific syntax or selection guidance beyond what the schema provides.

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?

The description names a specific verb and resource: deleting a file from structured storage. It explicitly distinguishes this from deleting the object record by stating that the object dataset remains, and it points to upload_file_to_object as the replacement path.

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?

It gives a clear prerequisite to check whether objects reference the file, plus a replacement workflow via upload_file_to_object. It does not explicitly contrast against onto_object_delete, though the scope difference is implied by saying only the file is removed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and "Rein lesend" merely restates that. The description does add one piece of non-annotation context: the call returns metadata and/or content. It says nothing about behavior when the identifier is unknown, whether content is inlined or by reference, or size/access constraints.

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?

Purpose is front-loaded, followed by usage condition and alternatives in two compact sentences. The trailing "| EN: file, image, document, attachment, upload" keyword block is search metadata rather than agent guidance and slightly dilutes the signal, including the somewhat misleading "upload".

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?

For a one-parameter, read-only tool with full annotations and 100% schema coverage, the description covers what it does, when to use it, and which siblings handle the adjacent cases. The residual gap is the ambiguous "Metadaten und/oder Inhalt" return shape, which is not disambiguated anywhere since there is no output schema.

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?

Schema coverage is 100%, so the object_id contract (32-hex udid) is already fully documented in the schema; the description only restates it as "Kennung". It adds no format, source, or discovery hint for obtaining the id, so the baseline 3 applies.

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?

States a specific verb and resource ("Eine Datei aus der strukturierten Ablage abrufen") plus scope (metadata and/or content), and explicitly names the two sibling tools it is not (upload_file_to_object, onto_scope_structuredimage_categories). The only slight fuzziness is "und/oder Inhalt", which leaves what is actually returned open, but an agent can still tell this apart from the upload and category tools.

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?

"Nutze es, wenn du die Datei ueber ihre Kennung kennst" gives a clear entry condition, and the alternative for the opposite case (upload) is named with its tool name. There is no explicit "do not use for X" beyond that, but the routing between retrieve/upload/categories is unambiguous.

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

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

Annotations already declare a non-readonly, non-destructive, non-idempotent write; the description adds substantive behavior beyond that: what actually gets written (1-field minimal definition), what the template copy mutates (fields carried over, visibility reset to the target scope, adminsql stripped for non-admins, buttons/template_file inherited), and the exact auth requirement with the resulting 403. Nothing here contradicts the annotations.

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?

The German block is dense but front-loaded: creation action first, template behavior second, permissions last. The trailing "| EN: form, form definition, fields, template, PDF, submission" is keyword padding rather than agent-relevant content, which costs it a point.

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?

For a mutating create tool with no output schema, it covers what is created, the auth precondition, the template-copy side effects, and the mandatory next step (onto_formdef_save). An agent has enough to invoke it correctly and chain it; the only residual gap is whether the new form's identifier is returned, which the naming convention makes inferable.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics for the template path — field takeover, visibility rewriting, adminsql removal. It does not cover the `formdef` or `answer_type` alternatives, and it calls the parameter "from_udid" while the schema names it `from`, a small mismatch an agent must resolve.

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?

The first two sentences state a specific verb and resource ("NEUES Formular anlegen") and precisely scope the effect: it creates the form object plus a minimal valid 1-field definition. It explicitly separates itself from the sibling onto_formdef_save (used afterwards to extend) and from onto_formdef_list_templates (source of the template udid), so an agent can route correctly.

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?

It gives clear usage context: call this first, then extend with onto_formdef_save, and use the from/template path when copying an existing definition (with a follow-up check of buttons/template_file). What's missing is explicit guidance on the alternative `formdef` path (pass a complete definition instead of the minimal scaffold) and on when NOT to create a copy at all.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Rein lesend' mostly restates structured data. What the description does add beyond annotations is that results are PUBLIC-scope only and that templates typically carry buttons/template_file, but nothing about result size, ordering, or whether non-public definitions are excluded silently.

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?

The useful content (scope, read-only, routing to create/show) is front-loaded and clear, but the trailing bilingual keyword block ('| EN: form, form definition, fields, template, PDF, submission') is pure keyword stuffing that consumes space without informing an agent's decision.

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?

With no output schema, the description usefully tells the agent what it gets back (visible PUBLIC templates usable via udid, including buttons/template_file) and what to do next. For a single-optional-parameter list tool with full annotations, this is close to sufficient, though the relationship to list_formdefs remains unexplained.

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?

Schema description coverage is 100% and the single optional parameter q is already documented as a title/name search term. The description never mentions the search parameter or its matching semantics, so it adds nothing beyond the schema; baseline 3 applies.

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?

The description states a specific verb and resource ('VORLAGEN auflisten: sichtbare Formulare im PUBLIC-Scope') and pins the scope to generic PUBLIC templates with the udid as the usable identifier. It differentiates itself from onto_formdef_create and onto_formdef_show by naming them, though it silently ignores the very similar sibling list_formdefs, which an agent might confuse it with.

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?

It gives concrete next-step routing: take the udid to onto_formdef_create + from_udid to build a company-specific copy, or onto_formdef_show to inspect fully, and it recommends PUBLIC templates as the easiest starting point because they ship with buttons/template_file. It lacks an explicit when-not clause, and the overlap with list_formdefs is left unresolved.

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

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

Annotations declare idempotent, non-destructive, non-read-only behavior, and the description adds substantial context beyond that: permission requirements, admin-only fields (adminsql/sql/sqlparameters), reserved keys, button type semantics, and template upload identity rules.

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?

Long but information-dense and front-loaded with the core save semantics, required fields, and field schema before the advanced template/button details. The unformatted wall of text with inline caps reduces scannability slightly.

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?

For a tool with a nested object parameter and no output schema, the description covers nested field grammar, widget enums, reserved keys, button configurations, PDF template mechanics, and placeholder syntax — everything needed to construct a valid call.

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?

Schema coverage is 100%, so baseline is 3, but the description goes far beyond: it enumerates the required nested keys (version int>=1, title, answer_type, fields), the per-field structure (key, widget, label, options, source, validation), the full widget vocabulary, and clarifies that buttons/template_file live inside the formdef JSON rather than as top-level params.

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?

States a specific verb+resource ('Formular-DEFINITION speichern') and explicitly positions it as the only write path for formdef, distinguishing it from read/list siblings and from onto_formdef_create referenced in the schema.

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?

Gives required fields, role prerequisites (form_writer/admin plus scope write access), and notes that name/scope_id also set master data. Lacks an explicit contrast with onto_formdef_create (new vs. overwrite), which would make it a 5.

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

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

Annotations already establish that this is a non-read-only, non-destructive, non-idempotent write operation. The description adds valuable behavioral context beyond annotations: the caller must manage the target scope, only a fixed operator set is allowed with no eval, optional effects can be attached, and the computed result is exposed as {result} for use in rules. It does not describe duplicate-key behavior or the exact creation response, so this is strong but not complete.

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?

The description is front-loaded with the core purpose, but it is long and repeats the body format and operator list that the schema already provides. The appended ZEITREGEL block is relevant to function authoring but adds considerable length, so the text is useful yet not fully concise.

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?

For a complex nested create tool with no output schema, the description covers the DSL, operator constraints, permissions, optional effects, and result usage well. It does not explain what the create call itself returns, such as the new function identifier, or how duplicate names/keys are handled, leaving a modest completeness gap.

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?

Schema description coverage is 100%, so the schema already documents the parameters in detail, including the body AST format, operator examples, and scope permission requirement. The description adds some meaning, such as the input type list and optional effects, but much of the body semantics duplicates the schema. Baseline 3 is appropriate.

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?

The description opens with a specific verb and resource: 'RECHENREGEL anlegen: eine Function.' It also distinguishes the tool from a trigger by explaining that a function has inputs and an expression and computes rather than reacts, which lets an agent identify the tool without inspecting its schema.

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?

The description gives clear context: this is for creating a function, unlike a trigger, and the result is later used in rules via run_function. It also states the permission prerequisite for scope_id. It does not explicitly enumerate when to choose this over sibling tools such as onto_trigger_create or onto_function_update, but the main usage context is clear.

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

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

Beyond annotations that already flag destructive and idempotent behavior, the description discloses that deletion is a soft-delete (status=deleted), that it is reversible, and that dependent run_function callers will fail afterward. It also specifies the authorization requirement can_manage_scope, giving the agent actionable behavioral context.

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?

The description is short and front-loads the core action, then adds reversibility, dependency warning, and permission requirements. The trailing English keyword list is somewhat redundant but not harmful; the bilingual phrasing adds slight density.

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?

For a single-parameter destructive mutation, the description covers reversibility, side effects on dependent functions, a pre-deletion check, and the required permission. No output schema is present, and nothing essential for correct invocation appears to be missing.

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?

The schema has 100% description coverage and defines the sole udid parameter as a 32-hex identifier. The description adds no additional parameter meaning, so the baseline of 3 is appropriate when the schema already carries the parameter documentation.

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?

The description clearly states a specific verb and resource: delete a function ('RECHENREGEL loeschen'), with English keywords confirming 'function'. It is distinguishable from create/update/run siblings by the delete action, though it does not explicitly contrast itself with other delete tools such as onto_object_delete or onto_actiondef_delete.

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?

It gives important context for when to be cautious: check via onto_trigger_index who uses the function before deleting, because run_function callers will break. It also states the required permission can_manage_scope, but it does not explicitly name updates or alternates to deletion.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Rein lesend' largely restates structured data. The description does add that these are server-side automations rather than user scripts, but says nothing about ordering, page-size session stickiness, or what a returned entry looks like.

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?

Front-loads what the tool does, then the routing guidance, then the mutating/trigger alternatives — a sensible order with no filler. The bilingual EN keyword suffix is mildly redundant but serves search relevance, so it is not penalized heavily.

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?

With no output schema, the description should signal what the list yields; it does so by indicating name/udid are retrievable. Combined with the safety annotations and fully documented paging params, an agent has enough to call this correctly, though return-field detail is left implicit.

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?

Schema coverage is 100% and both parameters (page, limit, including the 1..200 range and session-scoped default) are documented in the schema. The description adds no paging guidance of its own, so the baseline of 3 applies.

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?

States a specific verb and resource ('Alle hinterlegten Funktionen auflisten (serverseitige Automatiken)'), and the EN keyword tail (function, automation, expression, script, effect) disambiguates vocabulary. An agent can distinguish this from onto_function_run/create/update without inspecting schemas.

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?

Explicitly names the follow-up use case ('Nutze es, um den Namen/die udid fuer onto_function_run zu finden') and routes the other operations to their siblings: create/update for mutation, onto_trigger_index for time-based jobs. This is a full when/when-not/alternatives map.

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

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

The description usefully discloses that the effect is function-dependent and may write data ("kann Daten schreiben — also nicht rein lesend"), which goes beyond the annotations' generic readOnlyHint=false/destructiveHint=false. However it says nothing about permissions required, whether it runs synchronously, or what it returns, and the annotation pair could mislead an agent into expecting a non-destructive call.

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?

The core statement and the routing hint are front-loaded and every functional sentence earns its place. The trailing keyword list ("| EN: function, automation, expression, script, effect") is search padding rather than instruction.

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?

With no output schema, the description should indicate what the call produces (a function result, an execution report, or nothing). It covers the safety caveat but leaves the return behavior of an arbitrary server-side script unexplained, which is a meaningful gap for an agent deciding whether to invoke it.

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?

Schema coverage is 100% and both parameters are described in-schema, including the nested 'objekt' convention. The description only restates that inputs go in an inputs object, adding no syntax or convention detail beyond what the schema already carries.

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?

"Eine hinterlegte Funktion ausfuehren (serverseitige Automatik/Skript)" names a specific verb and resource and clarifies the object is user-defined server-side code, which separates it from create/update/delete siblings. It does not explicitly contrast with onto_object_execute_action, another plausible sibling, but the distinction is inferable.

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?

"Nutze es, wenn die Funktion bekannt ist; die verfuegbaren zeigt onto_function_index" gives an explicit condition plus a named alternative for the discovery case. No exclusion for when-not-to-use, but the gating condition is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description goes beyond them by spelling out exactly what destruction means ('body ersetzt die Definition vollstaendig') and by naming the required authorization (can_manage_scope im Ziel-Scope). It does not describe the response or what happens to omitted fields, so not a 5.

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?

Front-loaded with the action and the key destructive semantic in two short sentences; no filler. The trailing '| EN: function, automation, expression, script, effect' keyword list is search metadata rather than agent guidance and slightly dilutes the structure.

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?

For a 5-parameter destructive mutation with a nested body object and no output schema, the description covers the critical facts: full replacement semantics, format reference, and permission requirement. Minor gaps remain around the return value and the effect of changing scope_id.

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?

Schema description coverage is 100%, so both required and optional parameters are already documented, including the scope_id default to the previous scope. The description's note that body fully replaces the definition and points to onto_function_create largely duplicates the schema wording rather than adding new semantics.

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?

States a specific verb and resource: overwrite an existing Function (calculation rule), which clearly separates it from onto_function_create, onto_function_delete, onto_function_run. The domain gloss 'RECHENREGEL' plus the EN keyword tail adds searchable meaning, though the phrasing is terse and jargon-heavy.

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?

Usage is implied by 'bestehende Function ueberschreiben' and the pointer to onto_function_create for the body format, and a permission precondition (can_manage_scope in the target scope) is given. However, there is no explicit 'use create instead for new functions' or 'use delete to remove' routing, so the agent must infer the boundary.

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

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

Annotations already cover readOnly/destructive/idempotent/openWorld, and the description adds genuinely new behavioral facts: it mutates the model ('Aendert das Modell'), an unknown scope name aborts with 400, scope narrowing is only restrictive and never widening, and free SQL is admin-only. It does not describe the response or uniqueness/permission requirements, so it falls short of a 5.

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?

The purpose is front-loaded, but it is followed by a very long, unstructured wall of view_config detail that largely duplicates the schema, plus a noisy keyword line ('| EN: onto, interface, create, def') that carries no meaning. Mixed German/English and dense parenthetical nesting make the tool hard to scan.

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?

For a complex 8-parameter create tool with no output schema, the description covers the mutation semantics, scope behavior, and admin restriction well, but omits what is returned (e.g. created ID), name-uniqueness constraints, and any required permissions for a model-changing operation. It is adequate but leaves real gaps for the creation path.

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?

Schema description coverage is 100%, so the baseline is 3. The description does add cross-field semantics (the narrowing must also be mirrored into the interface description, placeholder quoting rules for text templates), but the bulk of the view_config prose restates structure the schema already documents, so it does not substantially exceed the schema.

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?

The opening sentence gives a specific verb and resource ('Eine neue Interface-Definition anlegen') plus a plain-language gloss ('neue Sicht/Maske'), and it explicitly routes updates of existing interfaces to onto_interface_update_def. An agent can distinguish this from its closest sibling without opening either schema.

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?

It states the triggering condition ('Nutze es, wenn ein Objekttyp eine zusaetzliche Ansicht bekommen soll') and names the alternative tool for the modification case. This is an explicit use-vs-alternative mapping, not just implied context.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but they do not say what is destroyed; the description fills that gap by clarifying that only the view is removed and objects/fields survive. It adds no detail about permission requirements or what happens to existing interface mappings (there is a sibling onto_interface_map_markers), which is the remaining behavioral gap.

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?

The key scoping constraint is front-loaded in the second sentence, and each sentence carries information. The trailing '| EN: onto, interface, delete, def' keyword tag is redundant noise that does not earn its place but is minor.

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?

For a one-parameter destructive delete, the description covers scope of destruction, a precondition check, and an alternative sibling, which is close to sufficient. It could mention effects on interface mappings or required rights to be fully complete.

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?

Schema description coverage is 100% for the single def_id parameter, so the schema already carries the meaning. The description adds no format, source, or lookup guidance for def_id, making the baseline of 3 appropriate.

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?

The description opens with a specific verb and resource ('Eine Interface-Definition entfernen') and immediately scopes what is removed versus preserved ('Entfernt die Sicht, NICHT die Objekte oder Felder'). It also distinguishes itself from the sibling onto_property_def_delete, so an agent can choose correctly without opening either schema.

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?

It gives a concrete precondition ('Pruefe vorher, ob Objekttypen das Interface verwenden') and routes single-field removal to onto_property_def_delete. It stops short of explicitly naming the when-not case for related siblings such as onto_interface_update_def or onto_object_delete, so it is strong but not exhaustive.

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

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

"Rein lesend" simply restates the readOnlyHint annotation rather than adding new information. The definition of what an interface is adds conceptual value, but it says nothing about result volume, pagination behavior, or the session-scoped limit rule that the schema hints at. With annotations already covering the safety profile, this is adequate but thin.

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?

The core content is front-loaded in three short sentences with no wasted clauses, and the alternative tool is placed last where it belongs. The trailing "| EN: onto, interface, index" keyword tag adds no semantic value and slightly dilutes the ending.

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?

For a two-parameter, read-only list tool with full schema coverage and complete annotations, the description supplies enough context to call it correctly. The absence of an output schema means a brief note on what the listing returns would have closed the remaining gap.

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?

Schema description coverage is 100% — both page and limit are documented in the schema, including the notable session-scoped limit behavior. The description adds no parameter guidance beyond that, so the baseline of 3 applies.

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?

States a specific verb and resource ("Alle Interfaces auflisten") and immediately defines the domain concept ("Sichten/Masken, die festlegen, welche Felder ein Objekt zeigt"), so an agent unfamiliar with the term knows what an interface is. It also names the sibling it is not ("Ein einzelnes Interface: onto_interface_show"), making disambiguation immediate.

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?

Explicitly states the use case: find the interface name needed for onto_object_create or for display. It also routes to the alternative tool onto_interface_show for single-record retrieval, so both the when-to-use and the when-not-to-use are covered.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description reinforces this by saying the operation is read-only and does not fetch external map data, but it adds little beyond the annotations and omits auth, rate-limit, or pagination context.

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?

The German description is front-loaded and efficient, with purpose first and usage/prerequisite guidance after. The appended EN keyword line and repeated 'Karten-/Karten-Ansichten' are slightly redundant but do not obscure the main instruction.

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?

For a two-parameter read-only tool with full schema coverage and rich annotations, the description supplies enough context: what it returns conceptually, that it is read-only, that no external map data is fetched, and that geocoding may be needed first. The unresolved choice between this tool and the identically responding sibling keeps it from being fully complete.

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?

Schema description coverage is 100%, so both name and bbox are already documented in the schema. The description does not add syntax or filtering semantics beyond what the schema provides; it only mentions that missing coordinates should be geocoded first.

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?

The description states a specific verb and resource: retrieving map markers for an interface, described as objects with coordinates for map display. It distinguishes the tool from onto_object_geocode by making geocoding a prerequisite for missing coordinates, and it identifies the duplicate ontouser_interface_map_markers sibling.

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?

It gives clear usage context: use it for map/map views, and set missing coordinates with onto_object_geocode first. It does not explain when to choose this tool over the identically responding ontouser_interface_map_markers sibling, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so 'Rein lesend' is redundant. The description still adds value by summarizing the returned content (fields, grouping, visibility) and by noting the identical-response relationship to ontouser_interface_show.

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?

The operative content is front-loaded and compact: read scope, safety, usage condition, alternative, and sibling equivalence. The trailing '| EN: onto, interface, show' keyword tag is mild filler but does not obscure the main guidance.

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?

With no output schema, the description supplies enough return-content context (fields, grouping, visibility) for the agent to know what a successful read provides. Annotations cover the safety profile, so the remaining gaps are minor.

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?

Schema coverage is 100% for the single required 'name' parameter, and the schema already labels it 'Interface-Name'. The description reinforces that the name is the lookup key but adds no syntax, format, or qualification details beyond the schema.

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?

The description states a specific verb and resource ('Ein einzelnes Interface vollstaendig lesen') and enumerates what is included: fields, grouping, visibility. It distinguishes itself from onto_interface_index and notes the identical-response sibling ontouser_interface_show, so the agent can select it confidently.

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?

Explicit routing is provided: use it when the name is known, and use onto_interface_index when it is not. It also clarifies that ontouser_interface_show returns the identical response, which prevents unnecessary tool shopping.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description reinforces this with "Der bisherige Wert ist danach weg (keine Historie, kein Undo)", which tells the agent the update replaces rather than patches. It also discloses validation and authorization behavior that annotations do not cover: an unknown scope name yields a 400, scopes can only narrow ("nur einschraenkend"), and free "sql" is admin-only.

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?

The German prose is front-loaded and purposeful, but the injected "| EN: onto, interface, update, def Verengung (optional): table.scopes ..." fragment splices a keyword line directly into a sentence about scope narrowing, which reads as an assembly artifact and breaks the flow. The genuinely useful scoping note is buried mid-paragraph instead of standing on its own.

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?

For an 8-parameter tool with a very complex nested view_config and no output schema, the description covers the items an agent would otherwise get wrong: that it is view-only, destructive with no undo, scope-narrowing only, and that field discovery goes through another tool. The replacement-vs-patch question is answered implicitly ("bisherige Wert ist danach weg") rather than stated outright, and there is no note on permissions beyond the admin-only SQL remark.

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?

Schema description coverage is already 100%, so the baseline is 3; the description earns above that by explaining the semantics of the scope parameter (table.scopes narrows rows of the view, is narrowing-only, unknown name = 400, must also be recorded in the interface description) and by clarifying that data_scope_id is for a view living in a different scope. It does not add anything for def_id, label, roles, or object_type_ids, which the schema already covers.

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?

"Eine bestehende Interface-Definition aendern (Felder, Reihenfolge, Sichtbarkeit)" is a specific verb plus resource plus the exact aspects that can be changed, and "Betrifft die Sicht, nicht die Daten" separates it from data-mutating siblings like onto_object_update. The word "bestehende" implicitly distinguishes it from onto_interface_create_def, but it never names that sibling the way it names onto_property_def_index.

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?

"Nutze es zum Anpassen einer Maske" gives a clear when-to-use, and it routes the agent to onto_property_def_index for discovering which fields exist. What is missing is an explicit boundary against onto_interface_create_def (new vs. existing) and onto_interface_delete_def, so the agent must infer the split from the word "bestehende".

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'Rein lesend' adds no new information. The description's extra value is only the pointer to the create/update siblings; nothing is said about ordering, pagination behavior, or the size of the definition list beyond what the schema already documents.

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?

Purpose, read-only note, and sibling routing come first in three tight sentences. The trailing '| EN: link, relation, edge, connection, graph' keyword list is retrieval-oriented padding that does not help an agent already reading the description, costing it a point.

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?

For a zero-required-parameter list tool with full schema coverage and full annotation coverage, the description covers purpose, safety, and sibling routing. It omits any hint of what fields a link definition entry contains, which would help when chaining into onto_object_create_link, but that is a minor gap.

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?

Schema description coverage is 100%, with page and limit both described in-schema (including the 1..200 range and the session-scoped limit). The description adds no meaning beyond that, so the baseline 3 applies.

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?

States a specific verb and resource ('Alle Link-Definitionen auflisten') and immediately disambiguates the domain concept with the parenthetical '(welche Beziehungen es zwischen Objekttypen gibt)'. It is clearly distinguishable from onto_object_create_link and the link_def mutation siblings.

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?

Explicitly names the downstream use case ('Nutze es, um den fuer onto_object_create_link noetigen Link-Typ zu finden') and routes the mutation cases to onto_link_create_def / onto_link_update_def. Both when-to-use and which-alternative-for-writes are covered.

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

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

Annotations already flag a non-idempotent, non-destructive write; the description adds substantial context beyond that: it is purely append-only, existing comments remain, a comment is its own object of type comment linked via hascomment, and deletion only sets status to deleted (removing it from the panel). Editing is explicitly impossible. No contradiction with readOnlyHint=false or destructiveHint=false.

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?

Front-loaded with the action and its append-only nature; the deletion and no-edit notes are genuinely useful rather than filler. It is on the long side and the trailing EN keyword list adds little, but overall it is information-dense.

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?

No output schema exists, and the description covers the lifecycle an agent needs: what gets created (a comment object with link), that properties are untouched, how to remove it, and that editing requires delete-and-rewrite. Nothing essential for a correct call is missing.

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?

Schema description coverage is 100%, so all three parameters (text, parent, scope_id) are already documented. The description mentions the parent object in prose and the comment udid in the deletion context but adds no format or scope_id semantics beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('Einen Kommentar an ein Objekt anhaengen') plus scope ('Verlaufseintrag mit Autor und Zeitstempel'), and explicitly separates itself from onto_object_set_property and onto_object_delete. An agent can distinguish this from the many onto_object_* siblings without opening a schema.

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?

Gives explicit use cases ('Notizen und Rueckfragen am Datensatz'), an explicit exclusion ('Es aendert KEINE Properties; dafuer onto_object_set_property'), and routes the delete/edit cases to onto_object_delete. When-to-use and when-not-to-use are both stated.

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

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

The description does add real behavioral context beyond structured fields: side effects are inherited from the underlying action and are irreversible, and a pre-filtering step is recommended. But this directly conflicts with destructiveHint=false while one of the allowed actions is 'delete', leaving the agent with two opposing signals about whether this can destroy data.

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?

Front-loaded with the purpose, followed by usage guidance and the irreversibility warning; every sentence carries information. The trailing '| EN: object, record, entry, …' keyword list is padding but brief.

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?

Given a 6-parameter mutation tool with no output schema and fully documented parameters, the description covers purpose, prerequisite, and irreversibility. It omits partial-failure semantics (all-or-nothing vs. per-object), which would matter for a bulk destructive operation.

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?

Schema description coverage is 100%, so every parameter including the action enum (delete | update) and the update-only fields is already documented in the schema. The description adds nothing parameter-specific, which is acceptable given full schema coverage, but no extra value is contributed.

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?

States a specific verb+resource+scope: apply the same action to many objects in a single call (bulk edit). It is clearly distinct from single-object mutation siblings such as onto_object_update or onto_object_execute_action, though it never names those siblings explicitly.

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?

Explicitly says when to reach for it (more than one record, instead of a loop of individual calls) and adds a concrete prerequisite: narrow the target set first with onto_object_index. Both the trigger condition and the useful alternative are named.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description adds real value on top: it writes to the database with "kein Trockenlauf" (no dry run), so the agent knows the effect is immediate, and it discloses that no links are created as a side effect. It does not say whether a validation failure leaves partial state, which keeps it below a 5.

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?

The core purpose and the no-dry-run warning are front-loaded, and each middle sentence carries a distinct constraint. The trailing "| EN: object, record, entry, property, link, search" keyword block is search fodder that dilutes an otherwise tight definition.

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?

For a create mutation with a fully described schema and no output schema, the definition covers what it does, that it persists immediately, what it requires, and which siblings to use instead. Given annotations already carry the safety profile, nothing essential for a correct call is missing beyond the required-field error noted above.

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?

Schema coverage is 100%, so the baseline would be 3, but the description actively misinforms: it says "Pflicht ist mindestens type" while the schema requires both type and name, so an agent following the prose would omit a required field. The explanations of properties (key → value) and interfaces (interface names) merely restate the schema descriptions and give no format or enum guidance for scope_id or external_id.

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?

"Ein neues Objekt anlegen" names a specific verb and resource, and the definition immediately scopes it against siblings by naming onto_object_update, onto_object_set_property and onto_object_create_link. An agent can distinguish create vs. update vs. link without opening any schema.

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?

Explicit routing: use it for new records, use onto_object_update / onto_object_set_property to change an existing one, and use onto_object_create_link when relations are needed. It also states a negative rule — no automatic links are created — which prevents a common wrong invocation.

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

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

Beyond the annotations it discloses the key behavioral trait: repeated calls do not create a duplicate edge but update it, which is upsert semantics an agent could not infer from readOnlyHint=false alone. It does not describe the response or any permission requirements, but the write/upsert profile is the important addition.

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?

The three German sentences are front-loaded and mostly earn their place, but the trailing '| EN: object, record, entry, property, link, search' keyword block is search-optimization padding with no value for tool selection.

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?

For a mutation tool with no output schema, the description covers the write behavior, idempotency-like semantics, and both related tools. Remaining gaps, such as return value or requirement of linkvalue for certain link types, are minor.

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?

Schema coverage is 100%, so all six parameters are documented in the schema. The description adds nothing about linktype syntax, when linkvalue vs linkvalue_free applies, or what scope_id does, so it neither compensates nor detracts.

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?

Specific verb and resource: connects two objects via a link type, creating an edge. It is clearly distinguishable from onto_object_update_link, which the description names as the tool for changing existing edges.

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?

It routes the agent to onto_link_index for available link types and to onto_object_update_link for modifying existing edges, which is explicit alternative guidance. It does not, however, clarify the overlap between this tool's own upsert behavior and update_link, leaving an ambiguity about which to pick for an existing edge.

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

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

The annotations declare destructiveHint=true and readOnlyHint=false, but the description adds behavior the annotations cannot convey: the delete is irreversible (no undo) and cascades to the object's properties. It also names the safe alternative path for soft-deactivation, which is exactly the context an agent needs before committing an unrecoverable action.

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?

Front-loaded with the action and its irreversibility, followed by the alternatives the ordering is exactly right for a destructive tool. The trailing '| EN: object, record, entry, property, link, search' synonym block is retrieval noise for an agent that has already selected the tool, keeping it just below 5.

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?

For a one-parameter destructive tool with full annotation coverage and no output schema, everything an agent needs is present: what is destroyed, that it cannot be undone, and which sibling to pick instead.

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?

There is a single required parameter with 100% schema description coverage ('Objekt-udid'), so the schema already carries the semantics. The description adds nothing beyond that, such as where a udid is obtained, though none is really required here. Baseline 3 applies.

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?

States a specific verb and resource ('Ein Objekt unwiderruflich loeschen') and adds scope that distinguishes it: the object's properties are removed along with it. It is clearly separable from onto_object_set_property and onto_object_bulk_action, and the German/English wording leaves no ambiguity.

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?

Explicitly states the condition ('nur, wenn der Datensatz wirklich entfallen soll'), the exclusion ('es gibt kein Undo'), and two named alternatives with their selecting conditions: set a status property via onto_object_set_property to deactivate/archive, or use onto_object_bulk_action for multiple objects. Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value on top by stating the blast radius (only the edge, not the linked objects) and irreversibility ("Unwiderruflich"). It omits permission/auth requirements and what a successful response looks like.

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?

The German core is well front-loaded and dense: purpose, non-destructive scope, irreversibility, inverse tool — four useful sentences in a row. But the trailing "| EN: object, record, entry, property, link, search" keyword list is SEO padding that earns no place, and the description is delivered in German where the tool title and schema are English, adding avoidable parsing cost.

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?

For a one-parameter destructive mutation with full annotation coverage and no output schema, the description covers what is destroyed and that it cannot be undone. It leaves the agent guessing how to obtain a valid link_udid and whether ontoname/scope context is required — a noticeable gap for a delete call where a wrong id is unrecoverable.

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?

Schema coverage is 100% for the single parameter, so the schema documents link_udid and the baseline of 3 applies. The description adds nothing about where a link_udid comes from (e.g. onto_object_show or onto_object_graph) or its format, so it does not compensate beyond the schema.

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?

States a specific verb and resource ("Verknuepfung zwischen zwei Objekten entfernen") and immediately scopes it against the most confusable sibling by clarifying that only the edge is removed, "NICHT die beteiligten Objekte" — which distinguishes it from onto_object_delete. An agent can select it without opening the schema.

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?

It names one related tool, onto_object_create_link, as the inverse operation ("Zum Anlegen derselben Kante"), which gives partial routing guidance. However it never addresses the closest ambiguity — when to delete-and-recreate versus use onto_object_update_link — and gives no prerequisites, so usage is only implied.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the concrete consequence ('Unwiderruflich' – irreversible) and clarifies that the parent object survives. It does not discuss permissions or return behavior, but for a two-parameter delete those gaps are minor.

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?

The core content is three tight sentences that front-load the action, then the consequence, then the alternatives. The trailing '(EN: object, record, entry, property, link, search)' keyword tag is search-index noise that does not help an agent decide anything.

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?

For a two-required-parameter destructive tool with full schema coverage and annotations that already carry the safety profile, the description covers action, irreversibility, and sibling routing. No output schema exists, so nothing further about return values is owed.

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?

Schema description coverage is 100%, so both parameters (udid, key) are already documented in the schema. The description adds no format, syntax, or lookup hints beyond what the schema states, so the baseline 3 applies.

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?

Specific verb plus resource ('ein einzelnes Property von einem Objekt entfernen') with an explicit outcome distinction: the value disappears, the object remains. It is immediately distinguishable from onto_object_delete and onto_object_set_property without opening either schema.

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?

Names both alternatives and the exact condition selecting each: use set_property with an empty value to merely clear a value, and onto_object_delete to remove the whole object. It also gives a positive use case (cleaning up faulty fields).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is partially covered. The description adds genuinely non-redundant behavior: the effect depends entirely on the action definition and may mutate properties, set links, or trigger follow-up processes — warning the agent it is not a read. It does not cover failure modes or whether prompts are mandatory for certain actions.

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?

The behavioral caveat and the pointer to onto_actiondef_list are front-loaded and earn their place. The trailing '| EN: object, record, entry, property, link, search' keyword string is filler that dilutes an otherwise tight two-sentence definition.

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?

For a non-idempotent mutation with annotations and no output schema, the description covers what it does, that effects vary by action, and where to find valid actions. It leaves open how the result should be interpreted and whether prompts are conditionally required, but no critical calling information is missing.

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?

Schema description coverage is 100%, so udid, action_key and prompts are already documented in the schema; baseline 3 applies. The description adds no extra semantics about the prompts object shape or how action_key values map to definitions beyond the schema's examples.

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?

States a specific verb+resource (execute a stored action/button/automation on an object) and distinguishes it from the discovery sibling by pointing to onto_actiondef_list for enumerating available actions. An agent can tell it apart from onto_actiondef_save/delete and onto_object_bulk_action.

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?

Gives a clear triggering condition ('when an action is offered on the object') and names onto_actiondef_list as the way to discover valid actions. It stops short of explicit exclusions, e.g. when to prefer onto_object_bulk_action or set_property directly, so no 5.

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

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

The description goes beyond the annotations by disclosing the two side effects that matter: it mutates the object and it depends on an external map service (open world), which implies latency and possible failure. It does not address overwrite semantics for existing coordinates or failure behavior, and the blanket "Schreibt in das Objekt" sits slightly at odds with the schema's apply=0 default, which only computes.

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?

The purpose, side effect, usage trigger and sibling alternative come first in three tight sentences. The trailing "| EN: object, record, entry, property, link, search" keyword block is pure noise for an invoking agent and dilutes the front-loading.

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?

There is no output schema, yet the description is adequate: an agent knows what is computed, when to call it, that it writes on demand and that it hits an external service. What it returns in the non-applying case, and what happens if the object lacks a usable address, remain unstated.

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?

Schema coverage is 100%, so all three parameters are already documented, including the apply and direction semantics. The description restates the address->coordinates mapping and the write-back behavior at a high level but adds no format, precedence, or edge-case detail beyond the schema; baseline 3 applies.

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?

States a concrete verb chain and resource: fetch coordinates for an object (address -> lat/lon), write them into the object, via an external map service. It explicitly marks the boundary against the sibling onto_interface_map_markers for map display, so the agent can separate geocoding from rendering.

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?

"Nutze es nach dem Anlegen eines Objekts mit Adresse, wenn Kartenmarker gebraucht werden" gives a clear trigger condition, and the sibling pointer names where to go for the display side. It does not cover the reverse-geocoding case or say when not to call it (e.g., coordinates already present), so it falls short of a full when/when-not treatment.

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

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

Annotations already declare readOnlyHint/idempotent/non-destructive, and 'Rein lesend' merely restates that. The description does add value beyond annotations by disclosing the return shape (Knoten + Kanten), which matters since there is no output schema. It stops short of describing graph depth, traversal limits, or how large link sets are handled.

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?

Front-loaded with the core action and return shape, then routing guidance — good ordering. The trailing '| EN: object, record, entry, property, link, search' keyword block is search-bait that adds no decision-relevant information and costs a small amount of concision.

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?

For a single-parameter read tool with no output schema, the description covers what is returned (nodes and edges), when to use it, and what to use instead. Only the shape/size of the returned graph at depth remains unaddressed, which is a minor gap given the annotations already carry the safety profile.

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